@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/src/predicate.evaluator.ts

@@ -0,0 +1,574 @@
+// In-memory evaluation of a folded condition against a row's own scalar fields, and
+// the `exists` questions for the rest. A to-one step whose references the row carries
+// is asked on the row they name, with the row's values; whatever else an existing row
+// leaves is asked about the row itself, by its identifier. A relation member on the
+// row is never read: core strips them, and any other caller could have forged one.
+// What cannot be asked is unknown, and the caller fails closed on it.
+
+import {
+	type AccessWhere,
+	mergeWhere,
+	translateWhere,
+} from "./aventara-where.translator.js";
+import type {
+	AccessComparison,
+	AccessLiteral,
+	AccessPolicies,
+} from "./policies-contract.js";
+import {
+	allOf,
+	andOf,
+	FALSE,
+	notOf,
+	nullSafe,
+	orOf,
+	ownOf,
+	type Resolved,
+	TRUE,
+} from "./scope.resolver.js";
+
+/**
+ * A row as core hands it to `can`: its scalar fields. A relation member on it is
+ * ignored; never put relation data a client sent on it.
+ */
+export type AccessRow = { readonly [field: string]: unknown };
+
+/** Core's `exists`: whether a row of `resource` meets `where`, unscoped. */
+export type AccessExists = (
+	resource: string,
+	where: AccessWhere,
+) => Promise<boolean>;
+
+/** One `exists` question the engine asked, and its answer. */
+export type AccessLookup = {
+	readonly resource: string;
+	readonly where: AccessWhere;
+	readonly answer: boolean;
+};
+
+/** A three-valued answer: decided, or not decidable from what the engine has. */
+export type AccessTruth = boolean | "unknown";
+
+/** Whether the row is about to be created, or already exists (an after check). */
+export type AccessRowKind = "new" | "existing";
+
+/** A field's type when `can` compares it by more than its JavaScript value (`types`). */
+type ComparedType = "bigint" | "datetime" | "decimal" | undefined;
+
+/** The type `can` compares `field` of `resource` by. */
+const typeOf = (
+	policies: AccessPolicies,
+	resource: string,
+	field: string,
+): ComparedType => ownOf(ownOf(policies.schema, resource)?.types, field);
+
+const DECIMAL = /^([+-]?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+
+/**
+ * A decimal's value as `{ sign, digits, point }`: `0.<digits> × 10^point`, with no
+ * leading or trailing zero in `digits` (zero is `{ sign: "", digits: "", point: 0 }`).
+ * `undefined` for text that is no decimal.
+ */
+export const decimalParts = (
+	text: string,
+):
+	| { readonly sign: "" | "-"; readonly digits: string; readonly point: number }
+	| undefined => {
+	const match = DECIMAL.exec(text);
+	if (match === null) {
+		return undefined;
+	}
+	// Indexed, not destructured: destructuring a match costs the type checker its
+	// iterator types (about 1,000 instantiations, the type budget's whole margin).
+	const sign = match[1] ?? "";
+	const whole = match[2] ?? "";
+	const fraction = match[3] ?? "";
+	const exponent = match[4] ?? "0";
+	const shift = Number(exponent);
+	if (!Number.isSafeInteger(shift)) {
+		return undefined;
+	}
+	let digits = whole + fraction;
+	let point = whole.length + shift;
+	const leading = digits.length - digits.replace(/^0+/, "").length;
+	digits = digits.slice(leading).replace(/0+$/, "");
+	point -= leading;
+	return digits === ""
+		? { sign: "", digits: "", point: 0 }
+		: { sign: sign === "-" ? "-" : "", digits, point };
+};
+
+/**
+ * An ISO-8601 date, or date and time with its offset (never a local time), to the
+ * millisecond at most.
+ */
+const INSTANT =
+	/^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|([+-])(\d{2}):(\d{2})))?$/;
+
+/**
+ * The epoch milliseconds of an ISO-8601 string that reads back as written: no
+ * February 30th, no hour 24, no offset past 23:59, nothing past the millisecond.
+ */
+const instantOfText = (text: string): number | undefined => {
+	const match = INSTANT.exec(text);
+	if (match === null) {
+		return undefined;
+	}
+	const part = (index: number): number => Number(match[index] ?? "0");
+	const year = part(1);
+	const month = part(2);
+	const day = part(3);
+	const hour = part(4);
+	const minute = part(5);
+	const second = part(6);
+	const millisecond = Number((match[7] ?? "").padEnd(3, "0"));
+	const local = Date.UTC(
+		year,
+		month - 1,
+		day,
+		hour,
+		minute,
+		second,
+		millisecond,
+	);
+	const read = new Date(local);
+	if (
+		read.getUTCFullYear() !== year ||
+		read.getUTCMonth() !== month - 1 ||
+		read.getUTCDate() !== day ||
+		read.getUTCHours() !== hour ||
+		read.getUTCMinutes() !== minute ||
+		read.getUTCSeconds() !== second ||
+		part(10) > 23 ||
+		part(11) > 59
+	) {
+		return undefined;
+	}
+	const offset = (part(10) * 60 + part(11)) * 60_000;
+	return match[9] === "-" ? local + offset : local - offset;
+};
+
+/** An instant's epoch milliseconds, from a valid `Date` or an ISO-8601 string that reads back as written. */
+export const instantOf = (value: unknown): number | undefined => {
+	if (value instanceof Date) {
+		const time = value.getTime();
+		return Number.isNaN(time) ? undefined : time;
+	}
+	return typeof value === "string" ? instantOfText(value) : undefined;
+};
+
+/** A decimal object's text: core's `AvDecimal`, an ORM's decimal, anything whose `toString()` is decimal digits. */
+const decimalText = (value: unknown): string | undefined =>
+	typeof value === "string"
+		? value
+		: typeof value === "number"
+			? Number.isFinite(value)
+				? String(value)
+				: undefined
+			: typeof value === "object" &&
+					value !== null &&
+					!(value instanceof Date) &&
+					!Array.isArray(value)
+				? String(value)
+				: undefined;
+
+/**
+ * The key a value is compared by, for a field of `type`: equal keys, equal values.
+ * `undefined` when the value is not one of the type's (a type mismatch).
+ */
+const comparisonKey = (value: unknown, type: ComparedType): unknown => {
+	switch (type) {
+		case "decimal": {
+			const text = decimalText(value);
+			const parts = text === undefined ? undefined : decimalParts(text);
+			return parts === undefined
+				? undefined
+				: `${parts.sign}${parts.digits}@${parts.point}`;
+		}
+		case "datetime":
+			return instantOf(value);
+		case "bigint":
+			return typeof value === "bigint"
+				? value
+				: typeof value === "number" && Number.isSafeInteger(value)
+					? BigInt(value)
+					: typeof value === "string" && /^-?\d+$/.test(value)
+						? BigInt(value)
+						: undefined;
+		default:
+			return typeof value === "string" ||
+				typeof value === "boolean" ||
+				(typeof value === "number" && Number.isFinite(value))
+				? value
+				: undefined;
+	}
+};
+
+/**
+ * One comparison of a row's value with a rule's, three-valued: a value of another
+ * type than the field's, or than the rule's, is `"unknown"`.
+ */
+const compare = (
+	rowValue: unknown,
+	cmp: AccessComparison,
+	value: AccessLiteral | readonly AccessLiteral[],
+	type: ComparedType,
+): AccessTruth => {
+	if (rowValue === null) {
+		// A comparison on NULL is false, except `equals: null` (IS NULL); a list never
+		// holds it for `can`.
+		return cmp === "eq" && value === null;
+	}
+	const actual = comparisonKey(rowValue, type);
+	const equal = (literal: AccessLiteral): AccessTruth => {
+		const expected = comparisonKey(literal, type);
+		return actual === undefined ||
+			expected === undefined ||
+			typeof actual !== typeof expected
+			? "unknown"
+			: actual === expected;
+	};
+	if (cmp === "eq" || cmp === "ne") {
+		if (value === null) {
+			return cmp === "ne";
+		}
+		const truth = equal(value as AccessLiteral);
+		return truth === "unknown" ? truth : cmp === "eq" ? truth : !truth;
+	}
+	let unknown = false;
+	for (const literal of value as readonly AccessLiteral[]) {
+		if (literal === null) {
+			continue;
+		}
+		const truth = equal(literal);
+		if (truth === true) {
+			return cmp === "in";
+		}
+		unknown ||= truth === "unknown";
+	}
+	return unknown ? "unknown" : cmp === "notIn";
+};
+
+/** A condition a row decided as neither true nor false: a value of the wrong type. */
+export type Unknown = { readonly k: "unknown" };
+
+const UNKNOWN: Unknown = { k: "unknown" };
+
+/** What evaluating on a row gives: `TRUE`, `FALSE`, `UNKNOWN`, or the residual. */
+export type Evaluated = Resolved | Unknown;
+
+/**
+ * A conjunction, three-valued. A part that is unknown makes the whole unknown unless
+ * another part is false: an unknown never waits on an `exists` question, and the
+ * caller fails closed on it.
+ */
+const and3 = (k: "and" | "all", args: readonly Evaluated[]): Evaluated =>
+	args.some((arg) => arg.k === "false")
+		? FALSE
+		: args.some((arg) => arg.k === "unknown")
+			? UNKNOWN
+			: (k === "and" ? andOf : allOf)(args as readonly Resolved[]);
+
+const or3 = (args: readonly Evaluated[]): Evaluated =>
+	args.some((arg) => arg.k === "true")
+		? TRUE
+		: args.some((arg) => arg.k === "unknown")
+			? UNKNOWN
+			: orOf(args as readonly Resolved[]);
+
+/** A row's own field: an inherited one is not on the row. */
+const fieldOf = (row: AccessRow, field: string): unknown =>
+	Object.hasOwn(row, field) ? row[field] : undefined;
+
+/**
+ * Evaluates what the row carries. The answer is `TRUE`, `FALSE`, `UNKNOWN` (a value
+ * of another type than its field's), or the residual condition: the part the row
+ * could not decide, with the decided parts folded away. A relation member on the row
+ * is ignored: every relation step stays whole in the residual, for `exists`. Each comparison is made by its
+ * field's type (`types`): a decimal by its digits, a datetime by its instant, a
+ * bigint exactly.
+ */
+export const evaluateOnRow = (
+	policies: AccessPolicies,
+	resource: string,
+	node: Resolved,
+	row: AccessRow,
+): Evaluated => {
+	switch (node.k) {
+		case "true":
+		case "false":
+			return node;
+		case "and":
+		case "all":
+			return and3(
+				node.k,
+				node.args.map((arg) => evaluateOnRow(policies, resource, arg, row)),
+			);
+		case "or":
+			return or3(
+				node.args.map((arg) => evaluateOnRow(policies, resource, arg, row)),
+			);
+		case "not": {
+			const arg = evaluateOnRow(policies, resource, node.arg, row);
+			return arg.k === "unknown" ? arg : notOf(arg);
+		}
+		case "cmp": {
+			const value = fieldOf(row, node.field);
+			if (value === undefined) {
+				return node;
+			}
+			const truth = compare(
+				value,
+				node.cmp,
+				node.value,
+				typeOf(policies, resource, node.field),
+			);
+			return truth === "unknown" ? UNKNOWN : truth ? TRUE : FALSE;
+		}
+		case "rel":
+		case "some":
+		case "every":
+		case "none":
+			// A relation is never read off the row: whoever built the row could have put
+			// anything there. It is decided through the row's identifier or references
+			// and `exists`, on what the database holds.
+			return node;
+	}
+};
+
+type AskContext = {
+	readonly policies: AccessPolicies;
+	readonly row: AccessRow;
+	readonly exists: AccessExists | undefined;
+	readonly lookups: AccessLookup[];
+};
+
+const ask = async (
+	context: AskContext,
+	resource: string,
+	where: AccessWhere,
+): Promise<AccessTruth> => {
+	if (context.exists === undefined) {
+		return "unknown";
+	}
+	const answer = (await context.exists(resource, where)) === true;
+	context.lookups.push({ resource, where, answer });
+	return answer;
+};
+
+/** An `exists` question's `where`: the row's own keys and the residual, null-safe. */
+const combine = (
+	policies: AccessPolicies,
+	resource: string,
+	where: AccessWhere,
+	residual: Resolved,
+): AccessWhere => {
+	const condition = translateWhere(nullSafe(policies, resource, residual));
+	return mergeWhere([where, condition]) ?? { AND: [where, condition] };
+};
+
+/** A row's value as an `exists` question's `where` states it: a `Date` as its ISO instant, a bigint as itself (exact). */
+const whereValue = (value: unknown): unknown =>
+	value instanceof Date ? value.toISOString() : value;
+
+/** Asks about an existing row, by its first identifier the row carries in full. */
+const askByIdentifier = async (
+	context: AskContext,
+	resource: string,
+	residual: Resolved,
+): Promise<AccessTruth> => {
+	const identifiers =
+		ownOf(context.policies.schema, resource)?.identifiers ?? [];
+	const identifier = identifiers.find((fields) =>
+		fields.every(
+			(field) =>
+				fieldOf(context.row, field) !== undefined &&
+				fieldOf(context.row, field) !== null,
+		),
+	);
+	if (identifier === undefined) {
+		return "unknown";
+	}
+	const where = Object.fromEntries(
+		identifier.map((field) => [
+			field,
+			{ equals: whereValue(fieldOf(context.row, field)) },
+		]),
+	);
+	return ask(
+		context,
+		resource,
+		combine(context.policies, resource, where, residual),
+	);
+};
+
+/**
+ * The reference values a to-one step's relation takes from the row: `undefined` when
+ * this end holds no references, or the row does not carry them all.
+ */
+const carriedReferences = (
+	context: AskContext,
+	resource: string,
+	node: Extract<Resolved, { k: "rel" }>,
+):
+	| {
+			readonly references: readonly string[];
+			readonly values: readonly unknown[];
+	  }
+	| undefined => {
+	const relation = ownOf(
+		ownOf(context.policies.schema, resource)?.relations,
+		node.relation,
+	);
+	if (
+		relation?.referenceFields === undefined ||
+		relation.references === undefined
+	) {
+		return undefined;
+	}
+	const values = relation.referenceFields.map((field) =>
+		fieldOf(context.row, field),
+	);
+	return values.some((value) => value === undefined)
+		? undefined
+		: { references: relation.references, values };
+};
+
+/** Whether a residual holds, outside any relation, a to-one step the row's references decide. */
+const stepsByReference = (
+	context: AskContext,
+	resource: string,
+	node: Resolved,
+): boolean => {
+	switch (node.k) {
+		case "and":
+		case "all":
+		case "or":
+			return node.args.some((arg) => stepsByReference(context, resource, arg));
+		case "not":
+			return stepsByReference(context, resource, node.arg);
+		case "rel":
+			return carriedReferences(context, resource, node) !== undefined;
+		default:
+			return false;
+	}
+};
+
+/**
+ * Decides a residual through `exists`. A to-one step whose references the row carries
+ * is asked on the row they name, with the row's own values: for a created row, and for
+ * an updated one too, since a caller may ask before the write, when the database still
+ * holds the old reference. Whatever else an existing row leaves is asked about the row
+ * itself, by its identifier (in one question when no step goes by reference); for a
+ * created row it is unknown.
+ */
+const askOn = async (
+	context: AskContext,
+	resource: string,
+	node: Resolved,
+	kind: AccessRowKind,
+): Promise<AccessTruth> => {
+	if (kind === "existing" && !stepsByReference(context, resource, node)) {
+		return node.k === "true"
+			? true
+			: node.k === "false"
+				? false
+				: askByIdentifier(context, resource, node);
+	}
+	switch (node.k) {
+		case "true":
+			return true;
+		case "false":
+			return false;
+		case "and":
+		case "all": {
+			let unknown = false;
+			for (const arg of node.args) {
+				const answer = await askOn(context, resource, arg, kind);
+				if (answer === false) {
+					return false;
+				}
+				unknown ||= answer === "unknown";
+			}
+			return unknown ? "unknown" : true;
+		}
+		case "or": {
+			let unknown = false;
+			for (const arg of node.args) {
+				const answer = await askOn(context, resource, arg, kind);
+				if (answer === true) {
+					return true;
+				}
+				unknown ||= answer === "unknown";
+			}
+			return unknown ? "unknown" : false;
+		}
+		case "not": {
+			const answer = await askOn(context, resource, node.arg, kind);
+			return answer === "unknown" ? "unknown" : !answer;
+		}
+		case "rel": {
+			const carried = carriedReferences(context, resource, node);
+			if (carried === undefined) {
+				return kind === "existing"
+					? askByIdentifier(context, resource, node)
+					: "unknown";
+			}
+			if (carried.values.some((value) => value === null)) {
+				return false;
+			}
+			const where = Object.fromEntries(
+				carried.references.map((field, index) => [
+					field,
+					{ equals: whereValue(carried.values[index]) },
+				]),
+			);
+			return ask(
+				context,
+				node.target,
+				combine(context.policies, node.target, where, node.where),
+			);
+		}
+		default:
+			return kind === "existing"
+				? askByIdentifier(context, resource, node)
+				: "unknown";
+	}
+};
+
+/**
+ * Decides a folded condition on a row: in memory first, then through `exists` for
+ * what the row does not carry. `"unknown"` when neither can decide.
+ */
+export const decideOnRow = async (args: {
+	readonly policies: AccessPolicies;
+	readonly resource: string;
+	readonly condition: Resolved;
+	readonly row: AccessRow;
+	readonly kind: AccessRowKind;
+	readonly exists: AccessExists | undefined;
+	readonly lookups: AccessLookup[];
+}): Promise<AccessTruth> => {
+	const residual = evaluateOnRow(
+		args.policies,
+		args.resource,
+		args.condition,
+		args.row,
+	);
+	if (residual.k === "true") {
+		return true;
+	}
+	if (residual.k === "false") {
+		return false;
+	}
+	if (residual.k === "unknown") {
+		return "unknown";
+	}
+	const context: AskContext = {
+		policies: args.policies,
+		row: args.row,
+		exists: args.exists,
+		lookups: args.lookups,
+	};
+	return askOn(context, args.resource, residual, args.kind);
+};