more fixes and tests

Author: ymc9

packages/runtime/src/enhancements/policy/constraint-solver.ts

@@ -10,7 +10,7 @@ import type {
 } from '../types';
 
 /**
- * A boolean constraint solver based on `logic-solver`.
+ * A boolean constraint solver based on `logic-solver`. Only boolean and integer types are supported.
  */
 export class ConstraintSolver {
     // a table for internalizing string literals

packages/runtime/src/enhancements/policy/handler.ts

@@ -1441,6 +1441,11 @@ export class PolicyProxyHandler<DbClient extends DbClientContract> implements Pr
 
     //#region Check
 
+    /**
+     * Checks if the given operation is possibly allowed by the policy, without querying the database.
+     * @param operation The CRUD operation.
+     * @param fieldValues Extra field value filters to be combined with the policy constraints.
+     */
     async check(
         operation: PolicyCrudKind,
         fieldValues?: Record<string, number | string | boolean | null>

packages/runtime/src/enhancements/policy/logic-solver.d.ts

@@ -1,43 +1,109 @@
+/**
+ * Type definitions for the `logic-solver` npm package.
+ */
 declare module 'logic-solver' {
+    /**
+     * A boolean formula.
+     */
     interface Formula {}
 
+    /**
+     * The `TRUE` formula.
+     */
     const TRUE: Formula;
 
+    /**
+     * The `FALSE` formula.
+     */
     const FALSE: Formula;
 
+    /**
+     * Boolean equivalence.
+     */
     export function equiv(operand1: Formula, operand2: Formula): Formula;
 
+    /**
+     * Bits equality.
+     */
     export function equalBits(bits1: Formula, bits2: Formula): Formula;
 
+    /**
+     * Bits greater-than.
+     */
     export function greaterThan(bits1: Formula, bits2: Formula): Formula;
 
+    /**
+     * Bits greater-than-or-equal.
+     */
     export function greaterThanOrEqual(bits1: Formula, bits2: Formula): Formula;
 
+    /**
+     * Bits less-than.
+     */
     export function lessThan(bits1: Formula, bits2: Formula): Formula;
 
+    /**
+     * Bits less-than-or-equal.
+     */
     export function lessThanOrEqual(bits1: Formula, bits2: Formula): Formula;
 
+    /**
+     * Logical AND.
+     */
     export function and(...args: Formula[]): Formula;
 
+    /**
+     * Logical OR.
+     */
     export function or(...args: Formula[]): Formula;
 
+    /**
+     * Logical NOT.
+     */
     export function not(arg: Formula): Formula;
 
+    /**
+     * Creates a bits variable with the given name and bit length.
+     */
     export function variableBits(baseName: string, N: number): Formula;
 
+    /**
+     * Creates a constant bits formula from the given whole number.
+     */
     export function constantBits(wholeNumber: number): Formula;
 
+    /**
+     * A solution to a constraint.
+     */
     interface Solution {
+        /**
+         * Returns a map of variable assignments.
+         */
         getMap(): object;
 
+        /**
+         * Evaluates the given formula against the solution.
+         */
         evaluate(formula: Formula): unknown;
     }
 
+    /**
+     * A constraint solver.
+     */
     class Solver {
+        /**
+         * Adds constraints to the solver.
+         */
         require(...args: Formula[]): void;
 
+        /**
+         * Adds negated constraints from the solver.
+         */
         forbid(...args: Formula[]): void;
 
+        /**
+         * Solves the constraints.
+         */
         solve(): Solution;
     }
 }

packages/runtime/src/enhancements/policy/policy-utils.ts

@@ -565,6 +565,9 @@ export class PolicyUtil extends QueryUtils {
 
     //#region Checker
 
+    /**
+     * Gets checker constraints for the given model and operation.
+     */
     getCheckerConstraint(model: string, operation: PolicyCrudKind): ReturnType<CheckerFunc> | boolean {
         const checker = this.getModelChecker(model);
         if (!checker) {
@@ -576,9 +579,11 @@ export class PolicyUtil extends QueryUtils {
             return provider;
         }
 
-        if (!provider) {
-            throw this.unknownError(`unable to load authorization guard for ${model}`);
+        if (typeof provider !== 'function') {
+            throw this.unknownError(`unable to ${operation} checker for ${model}`);
         }
+
+        // call checker function
         return provider({ user: this.user });
     }
 

packages/runtime/src/enhancements/types.ts

@@ -33,31 +33,55 @@ export interface CommonEnhancementOptions {
  */
 export type PolicyFunc = (context: QueryContext, db: CrudContract) => object;
 
+/**
+ * Function for checking if an operation is possibly allowed.
+ */
 export type CheckerFunc = (context: CheckerContext) => CheckerConstraint;
 
+/**
+ * Supported checker constraint checking value types.
+ */
 export type ConstraintValueTypes = 'boolean' | 'number' | 'string';
 
+/**
+ * Free variable constraint
+ */
 export type VariableConstraint = { kind: 'variable'; name: string; type: ConstraintValueTypes };
 
+/**
+ * Constant value constraint
+ */
 export type ValueConstraint = {
     kind: 'value';
     value: number | boolean | string;
     type: ConstraintValueTypes;
 };
 
+/**
+ * Terms for comparison constraints
+ */
 export type ComparisonTerm = VariableConstraint | ValueConstraint;
 
+/**
+ * Comparison constraint
+ */
 export type ComparisonConstraint = {
     kind: 'eq' | 'gt' | 'gte' | 'lt' | 'lte';
     left: ComparisonTerm;
     right: ComparisonTerm;
 };
 
+/**
+ * Logical constraint
+ */
 export type LogicalConstraint = {
     kind: 'and' | 'or' | 'not';
     children: CheckerConstraint[];
 };
 
+/**
+ * Operation allowability checking constraint
+ */
 export type CheckerConstraint = ValueConstraint | VariableConstraint | ComparisonConstraint | LogicalConstraint;
 
 /**

packages/runtime/src/types.ts

@@ -58,10 +58,19 @@ export type QueryContext = {
     preValue?: any;
 };
 
+/**
+ * Context for checking operation allowability.
+ */
 export type CheckerContext = {
+    /**
+     * Current user
+     */
     user?: AuthUser;
 
-    fieldValues?: Record<string, string | number | boolean | null>;
+    /**
+     * Extra field value filters.
+     */
+    fieldValues?: Record<string, string | number | boolean>;
 };
 
 /**

packages/schema/src/plugins/enhancer/enhance/checker-type-generator.ts

@@ -5,6 +5,17 @@ import { P, match } from 'ts-pattern';
 
 /**
  * Generates a `ModelCheckers` interface that contains a `check` method for each model in the schema.
+ *
+ * E.g.:
+ *
+ * ```ts
+ * type CheckerOperation = 'create' | 'read' | 'update' | 'delete';
+ *
+ * export interface ModelCheckers {
+ *    user: { check(op: CheckerOperation, args?: { email?: string; age?: number; }): Promise<boolean> },
+ *    ...
+ * }
+ * ```
  */
 export function generateCheckerType(model: Model) {
     return `

packages/schema/src/plugins/enhancer/policy/constraint-transformer.ts

@@ -20,37 +20,52 @@ import {
 } from '@zenstackhq/sdk/ast';
 import { P, match } from 'ts-pattern';
 
+/**
+ * Options for {@link ConstraintTransformer}.
+ */
 export type ConstraintTransformerOptions = {
     authAccessor: string;
 };
 
+/**
+ * Transform a set of allow and deny rules into a single constraint expression.
+ */
 export class ConstraintTransformer {
+    // a counter for generating unique variable names
     private varCounter = 0;
 
     constructor(private readonly options: ConstraintTransformerOptions) {}
 
+    /**
+     * Transforms a set of allow and deny rules into a single constraint expression.
+     */
     transformRules(allows: Expression[], denies: Expression[]): string {
+        // reset state
         this.varCounter = 0;
 
         if (allows.length === 0) {
+            // unconditionally deny
             return this.value('false', 'boolean');
         }
 
         let result: string;
 
+        // transform allow rules
         const allowConstraints = allows.map((allow) => this.transformExpression(allow));
         if (allowConstraints.length > 1) {
             result = this.and(...allowConstraints);
         } else {
             result = allowConstraints[0];
         }
 
+        // transform deny rules and compose
         if (denies.length > 0) {
             const denyConstraints = denies.map((deny) => this.transformExpression(deny));
             result = this.and(result, this.not(this.or(...denyConstraints)));
         }
 
-        console.log(`Constraint transformation result:\n${JSON.stringify(result, null, 2)}`);
+        // DEBUG:
+        // console.log(`Constraint transformation result:\n${JSON.stringify(result, null, 2)}`);
 
         return result;
     }
@@ -105,22 +120,30 @@ export class ConstraintTransformer {
     }
 
     private transformReference(expr: ReferenceExpr) {
+        // top-level reference is transformed into a named variable
         return this.variable(expr.target.$refText, 'boolean');
     }
 
     private transformMemberAccess(expr: MemberAccessExpr) {
         if (isThisExpr(expr.operand)) {
+            // "this.x" is transformed into a named variable
             return this.variable(expr.member.$refText, 'boolean');
         }
+
+        // other member access expressions are not supported and thus
+        // transformed into a free variable
         return this.nextVar();
     }
 
     private transformBinary(expr: BinaryExpr): string {
-        return match(expr.operator)
-            .with('&&', () => this.and(this.transformExpression(expr.left), this.transformExpression(expr.right)))
-            .with('||', () => this.or(this.transformExpression(expr.left), this.transformExpression(expr.right)))
-            .with(P.union('==', '!=', '<', '<=', '>', '>='), () => this.transformComparison(expr))
-            .otherwise(() => this.nextVar());
+        return (
+            match(expr.operator)
+                .with('&&', () => this.and(this.transformExpression(expr.left), this.transformExpression(expr.right)))
+                .with('||', () => this.or(this.transformExpression(expr.left), this.transformExpression(expr.right)))
+                .with(P.union('==', '!=', '<', '<=', '>', '>='), () => this.transformComparison(expr))
+                // unsupported operators (e.g., collection predicate) are transformed into a free variable
+                .otherwise(() => this.nextVar())
+        );
     }
 
     private transformUnary(expr: UnaryExpr): string {
@@ -134,6 +157,7 @@ export class ConstraintTransformer {
         const rightOperand = this.getComparisonOperand(expr.right);
 
         if (leftOperand === undefined || rightOperand === undefined) {
+            // if either operand is not supported, transform into a free variable
             return this.nextVar();
         }
 
@@ -150,6 +174,7 @@ export class ConstraintTransformer {
 
         let result = `{ kind: '${op}', left: ${leftOperand}, right: ${rightOperand} }`;
         if (expr.operator === '!=') {
+            // transform "!=" into "not eq"
             result = `{ kind: 'not', children: [${result}] }`;
         }
 
@@ -163,6 +188,7 @@ export class ConstraintTransformer {
 
         const fieldAccess = this.getFieldAccess(expr);
         if (fieldAccess) {
+            // model field access is transformed into a named variable
             const mappedType = this.mapType(expr);
             if (mappedType) {
                 return this.variable(fieldAccess.name, mappedType);
@@ -173,6 +199,9 @@ export class ConstraintTransformer {
 
         const authAccess = this.getAuthAccess(expr);
         if (authAccess) {
+            // `auth().` access is transformed into a runtime boolean value if it
+            // doesn't evaluate to undefined (due to ?. chaining), otherwise into
+            // a named variable
             const fieldAccess = `${this.options.authAccessor}?.${authAccess}`;
             const mappedType = this.mapType(expr);
             if (mappedType) {

packages/schema/src/plugins/enhancer/policy/policy-guard-generator.ts

@@ -88,11 +88,13 @@ export class PolicyGenerator {
 
         const models = getDataModels(model);
 
+        // policy guard functions
         const policyMap: Record<string, Record<string, string | boolean | object>> = {};
         for (const model of models) {
             policyMap[model.name] = await this.generateQueryGuardForModel(model, sf);
         }
 
+        // CRUD checker functions
         const checkerMap: Record<string, Record<string, string | boolean>> = {};
         for (const model of models) {
             checkerMap[model.name] = await this.generateCheckerForModel(model, sf);