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

package/src/policies.decider.ts

@@ -0,0 +1,662 @@
+// The decisions a policies file makes: `can`, `grantsOf`, `scopeOf` and `fieldsOf`,
+// answered from the file alone. Default deny, any grant allows, any deny wins, order
+// never matters. The engine (`access.engine.ts`) runs this with its lock, guardrails,
+// decision observer and `explain` around it; `avaccess generate` copies this module,
+// with the modules it imports, into a service's generated client.
+//
+// Like those modules, it imports nothing but them: no Node.js, no package.
+
+import {
+	type AccessWhere,
+	translateAnswer,
+	translateWhere,
+} from "./aventara-where.translator.js";
+import { type CanonicalJson, canonicalJson } from "./canonical-json.writer.js";
+import type {
+	AccessAction,
+	AccessGrantRule,
+	AccessOrigin,
+	AccessPolicies,
+} from "./policies-contract.js";
+import {
+	type AccessExists,
+	type AccessLookup,
+	type AccessRow,
+	type AccessTruth,
+	decideOnRow,
+	type Evaluated,
+	evaluateOnRow,
+} from "./predicate.evaluator.js";
+import {
+	FALSE,
+	type FoldedDeny,
+	type FoldedGrant,
+	foldDenies,
+	foldGrants,
+	governedFor,
+	nullSafe,
+	orOf,
+	ownOf,
+	principalFactsOf,
+	type Resolved,
+	rulesFor,
+	scopeCondition,
+	TRUE,
+} from "./scope.resolver.js";
+import { sha256Hex } from "./sha256.digest.js";
+
+/** What every question states. */
+export type AccessQuestion = {
+	/** What the host derived for the request: an object, or `null` (anonymous). */
+	readonly principal: unknown;
+	readonly origin: AccessOrigin;
+	readonly resource: string;
+};
+
+/** `can`: without a row, admission; with one, the row a create inserts or an update leaves. */
+export type AccessCanQuestion = AccessQuestion & {
+	readonly action: AccessAction;
+	readonly row?: AccessRow;
+	/**
+	 * On an update with a `row` only: the row as it was before the update. One update
+	 * grant must then cover both rows, its `where` this one and its `where` and
+	 * `after` the row the update leaves. Without it, any update grant that covers the
+	 * row the update leaves lets it in. Read nowhere else.
+	 */
+	readonly before?: AccessRow;
+	/**
+	 * On an update with a `row` only: what `grantsOf` answered about the row before the
+	 * update, asked before the write. The grant that covers `row` (its `where` and
+	 * `after`) must then be one of these. With `before` too, each such grant's `where`
+	 * is checked on `before` in memory, so a list from another row or principal fails
+	 * on a scalar condition; a relation condition on it is not asked again: it was
+	 * decided before anything the update wrote. Read nowhere else.
+	 */
+	readonly beforeGrants?: readonly string[];
+	readonly exists?: AccessExists;
+};
+
+/**
+ * `grantsOf`: the update grants that cover `row`, the row an update will change, as it
+ * is now. Ask it before the write, and hand its answer back to `can` as `beforeGrants`.
+ */
+export type AccessGrantsQuestion = AccessQuestion & {
+	readonly action: "update";
+	readonly row: AccessRow;
+	readonly exists?: AccessExists;
+};
+
+/** `scopeOf`: the rows the principal may read, update or delete. */
+export type AccessScopeQuestion = AccessQuestion & {
+	readonly action: "read" | "update" | "delete";
+};
+
+/** `fieldsOf`: reading, or writing by one action. */
+export type AccessFieldsQuestion = AccessQuestion &
+	(
+		| { readonly access: "read" }
+		| { readonly access: "write"; readonly action?: "create" | "update" }
+	);
+
+/** `fieldsOf`'s answer: fields usable on every reachable row, and fields usable on some rows. */
+export type AccessFields = {
+	readonly always: "all" | readonly string[];
+	readonly perRow: { readonly [field: string]: AccessWhere };
+};
+
+/** How one rule took part in a decision. */
+export type AccessRuleOutcome =
+	| "matched"
+	| "not matched"
+	| "unknown"
+	| "not asked";
+
+/** How each rule took part in one `can` decision, and the `exists` lookups it made. */
+export type DecisionTrace = {
+	readonly grants: Map<FoldedGrant, AccessRuleOutcome>;
+	readonly denies: Map<FoldedDeny, AccessRuleOutcome>;
+	readonly lookups: AccessLookup[];
+};
+
+/** A trace with nothing in it yet. */
+export const newTrace = (): DecisionTrace => ({
+	grants: new Map(),
+	denies: new Map(),
+	lookups: [],
+});
+
+/**
+ * The Resources where the row an update leaves can fail what allowed the update:
+ * an update grant whose condition reads the row (a `where`, an `after`, a role held
+ * on a row), or an update deny with a `where`. Core asks `can` about each row such
+ * an update changed, and refuses these updates where it has no interactive
+ * transaction to roll one back in.
+ */
+export const afterChecksOf = (
+	policies: AccessPolicies,
+): Record<string, "update"[]> => {
+	const afterChecks: Record<string, "update"[]> = {};
+	const reads = (grant: AccessGrantRule): boolean =>
+		grant.where !== undefined ||
+		grant.after !== undefined ||
+		grant.in !== undefined ||
+		grant.subjects.some((subject) => {
+			const role = ownOf(policies.roles, subject);
+			return role !== undefined && "on" in role;
+		});
+	for (const grant of policies.grants) {
+		if (
+			grant.resource !== "*" &&
+			grant.actions.includes("update") &&
+			reads(grant)
+		) {
+			afterChecks[grant.resource] = ["update"];
+		}
+	}
+	for (const deny of policies.denies) {
+		if (
+			deny.resource !== "*" &&
+			deny.where !== undefined &&
+			(deny.actions === "*" || deny.actions.includes("update"))
+		) {
+			afterChecks[deny.resource] = ["update"];
+		}
+	}
+	return afterChecks;
+};
+
+/**
+ * The fields each grant's `write.except` locks. A relation and its reference fields
+ * are locked together: writing the relation (`$connect`, `$set`) writes those
+ * fields, and writing a reference field moves the relation, so naming either one
+ * locks both.
+ */
+const lockedFieldsOf = (
+	policies: AccessPolicies,
+): Map<AccessGrantRule, ReadonlySet<string>> => {
+	const locks = new Map<AccessGrantRule, ReadonlySet<string>>();
+	for (const grant of policies.grants) {
+		if (grant.write === undefined) {
+			continue;
+		}
+		const named = new Set(grant.write.except);
+		const locked = new Set(named);
+		const relations = ownOf(policies.schema, grant.resource)?.relations ?? {};
+		for (const [relation, fact] of Object.entries(relations)) {
+			const references = fact.referenceFields ?? [];
+			if (named.has(relation) || references.some((field) => named.has(field))) {
+				locked.add(relation);
+				for (const field of references) {
+					locked.add(field);
+				}
+			}
+		}
+		locks.set(grant, locked);
+	}
+	return locks;
+};
+
+/**
+ * What is wrong with a `fieldsOf` question the types rule out but a caller can still
+ * send, or `undefined`: answered as asked, it would read as a read, or as no field.
+ */
+export const fieldsQuestionProblem = (
+	question: AccessFieldsQuestion,
+): string | undefined => {
+	const { access, action } = question as {
+		readonly access?: unknown;
+		readonly action?: unknown;
+	};
+	const fits =
+		access === "read"
+			? action === undefined
+			: access === "write" &&
+				(action === undefined || action === "create" || action === "update");
+	return fits
+		? undefined
+		: `fieldsOf takes \`access: "read"\`, or \`access: "write"\` with an optional \`action\` ("create" or "update"); it was asked ${JSON.stringify({ access, action })}`;
+};
+
+const outcomeOf = (truth: AccessTruth): AccessRuleOutcome =>
+	truth === "unknown" ? "unknown" : truth ? "matched" : "not matched";
+
+const isDecided = (
+	node: Evaluated,
+): node is { readonly k: "true" } | { readonly k: "false" } =>
+	node.k === "true" || node.k === "false";
+
+/**
+ * What is wrong with a `grantsOf` question the types rule out but a caller can still
+ * send, or `undefined`: it asks about an update, and nothing else.
+ */
+export const grantsQuestionProblem = (
+	question: AccessGrantsQuestion,
+): string | undefined => {
+	const { action } = question as { readonly action?: unknown };
+	return action === "update"
+		? undefined
+		: `grantsOf takes \`action: "update"\`; it was asked ${JSON.stringify({ action })}`;
+};
+
+/** The questions a policies file answers. */
+export type PoliciesDecider = {
+	/** `can`, recording each rule's part in the answer in `trace`. */
+	can(
+		question: AccessCanQuestion,
+		trace: DecisionTrace,
+	): boolean | Promise<boolean>;
+	/**
+	 * The keys of the update grants whose `where`, and their subject's row condition,
+	 * hold on `row` as it is now: opaque and stable for this file, never rule data.
+	 * None when an update deny is decided on `row` in memory.
+	 */
+	grantsOf(
+		question: AccessGrantsQuestion,
+	): readonly string[] | Promise<readonly string[]>;
+	scopeOf(question: AccessScopeQuestion): boolean | AccessWhere;
+	fieldsOf(question: AccessFieldsQuestion): AccessFields;
+};
+
+/** Whether two field lists name the same fields. */
+const sameFields = (a: readonly string[], b: readonly string[]): boolean =>
+	a.length === b.length && a.every((field) => b.includes(field));
+
+/** The decisions of one policies file, already checked. */
+export const createDecider = (file: AccessPolicies): PoliciesDecider => {
+	const locks = lockedFieldsOf(file);
+	// A grant's key: a short hash of the file's grants, in their order, then its place
+	// in the file and its subject's place in the grant. It names a grant for one
+	// subject without carrying any of its data, a list from another file names no grant
+	// of this one, and it is the same for the folded grant `grantsOf` reads (its
+	// `where`) and the one `can` reads (its `where` and `after`).
+	const mark = sha256Hex(
+		canonicalJson(file.grants as unknown as CanonicalJson),
+	).slice(0, 8);
+	const places = new Map(file.grants.map((grant, index) => [grant, index]));
+	const keyOf = (grant: FoldedGrant): string =>
+		`${mark}:${places.get(grant.grant) ?? -1}.${grant.grant.subjects.indexOf(grant.subject)}`;
+
+	const can = (
+		question: AccessCanQuestion,
+		trace: DecisionTrace,
+	): boolean | Promise<boolean> => {
+		const facts = principalFactsOf(question.principal, question.origin);
+		const { grants, denies } = rulesFor(
+			file,
+			question.resource,
+			question.action,
+		);
+		const { row } = question;
+
+		if (row === undefined) {
+			// Admission: could this principal ever do this? Row conditions are the scope's.
+			const folded = foldGrants(file, grants, facts);
+			const foldedDenies = foldDenies(file, denies, facts);
+			for (const grant of folded) {
+				trace.grants.set(
+					grant,
+					grant.condition.k === "false" ? "not matched" : "matched",
+				);
+			}
+			for (const deny of foldedDenies) {
+				trace.denies.set(
+					deny,
+					deny.condition.k === "true" ? "matched" : "not matched",
+				);
+			}
+			return (
+				folded.some((grant) => grant.condition.k !== "false") &&
+				!foldedDenies.some((deny) => deny.condition.k === "true")
+			);
+		}
+
+		if (typeof row !== "object" || row === null) {
+			return false;
+		}
+		// The row a create inserts, or the row an update leaves (core's after check, or
+		// any caller's): an update's row must still meet the `where` and the `after` of
+		// one update grant, and no update deny may match it.
+		const isUpdate = question.action === "update";
+		const kind = question.action === "create" ? "new" : "existing";
+		// With the row before the update: the grant that covers the row
+		// the update leaves must be one whose `where` covered the row before it, so no
+		// update moves a row from the rows one grant reaches to another's. With
+		// `beforeGrants`, what covered it was decided before the write (`grantsOf`):
+		// `before` is still held to each listed grant's `where` in memory, since the list
+		// is the caller's to hand back, but a relation condition on it is not asked again.
+		const beforeGrants = isUpdate ? question.beforeGrants : undefined;
+		if (
+			beforeGrants !== undefined &&
+			(!Array.isArray(beforeGrants) ||
+				beforeGrants.some((key) => typeof key !== "string"))
+		) {
+			return false;
+		}
+		const coveredBefore =
+			beforeGrants === undefined ? undefined : new Set(beforeGrants);
+		const before = isUpdate ? question.before : undefined;
+		if (
+			before !== undefined &&
+			(typeof before !== "object" || before === null)
+		) {
+			return false;
+		}
+		const folded = foldGrants(file, grants, facts, isUpdate);
+		const reached =
+			before === undefined ? undefined : foldGrants(file, grants, facts);
+		const foldedDenies = foldDenies(file, denies, facts);
+
+		const grantResiduals: {
+			readonly grant: FoldedGrant;
+			readonly residual: Resolved;
+			/** What the row before the update leaves of the grant's `where`; `undefined` when decided true. */
+			readonly prior: Resolved | undefined;
+		}[] = [];
+		let granted = false;
+		for (const [index, grant] of folded.entries()) {
+			if (coveredBefore !== undefined && !coveredBefore.has(keyOf(grant))) {
+				// It did not cover the row before the update.
+				trace.grants.set(grant, "not matched");
+				continue;
+			}
+			const residual = evaluateOnRow(
+				file,
+				question.resource,
+				grant.condition,
+				row,
+			);
+			// Folded alike, the two lists pair grant for grant; a missing pair covers nothing.
+			const evaluated =
+				reached === undefined || before === undefined
+					? undefined
+					: evaluateOnRow(
+							file,
+							question.resource,
+							reached?.[index]?.condition ?? FALSE,
+							before,
+						);
+			// Listed in `beforeGrants`: what is left of its `where` on `before` is a relation
+			// condition `grantsOf` decided before the write; only a decided false, or a
+			// value of the wrong type, refuses.
+			const prior =
+				coveredBefore !== undefined &&
+				evaluated?.k !== "false" &&
+				evaluated?.k !== "unknown"
+					? undefined
+					: evaluated;
+			if (residual.k === "unknown" || prior?.k === "unknown") {
+				// A value of the wrong type: no grant.
+				trace.grants.set(grant, "unknown");
+			} else if (residual.k === "false" || prior?.k === "false") {
+				trace.grants.set(grant, "not matched");
+			} else if (
+				residual.k === "true" &&
+				(prior === undefined || prior.k === "true")
+			) {
+				trace.grants.set(grant, "matched");
+				granted = true;
+			} else {
+				trace.grants.set(grant, "not asked");
+				grantResiduals.push({
+					grant,
+					residual,
+					prior: prior === undefined || prior.k === "true" ? undefined : prior,
+				});
+			}
+		}
+		const denyResiduals: {
+			readonly deny: FoldedDeny;
+			readonly residual: Resolved;
+		}[] = [];
+		for (const deny of foldedDenies) {
+			const residual = evaluateOnRow(
+				file,
+				question.resource,
+				deny.condition,
+				row,
+			);
+			if (residual.k === "unknown") {
+				// A value of the wrong type: the deny counts (fail closed).
+				trace.denies.set(deny, "unknown");
+				return false;
+			}
+			if (isDecided(residual)) {
+				trace.denies.set(
+					deny,
+					residual.k === "true" ? "matched" : "not matched",
+				);
+				if (residual.k === "true") {
+					return false;
+				}
+			} else {
+				trace.denies.set(deny, "not asked");
+				denyResiduals.push({ deny, residual });
+			}
+		}
+		if (!granted && grantResiduals.length === 0) {
+			return false;
+		}
+		if (denyResiduals.length === 0 && granted) {
+			return true;
+		}
+
+		const ask = (
+			condition: Resolved,
+			on: AccessRow = row,
+		): Promise<AccessTruth> =>
+			decideOnRow({
+				policies: file,
+				resource: question.resource,
+				condition,
+				row: on,
+				kind,
+				exists: question.exists,
+				lookups: trace.lookups,
+			});
+		return (async () => {
+			for (const { deny, residual } of denyResiduals) {
+				const truth = await ask(residual);
+				trace.denies.set(deny, outcomeOf(truth));
+				// A deny that cannot be decided counts: fail closed.
+				if (truth !== false) {
+					return false;
+				}
+			}
+			if (granted) {
+				return true;
+			}
+			for (const { grant, residual, prior } of grantResiduals) {
+				let truth = await ask(residual);
+				if (truth === true && prior !== undefined && before !== undefined) {
+					truth = await ask(prior, before);
+				}
+				trace.grants.set(grant, outcomeOf(truth));
+				if (truth === true) {
+					return true;
+				}
+			}
+			return false;
+		})();
+	};
+
+	const fieldsOf = (question: AccessFieldsQuestion): AccessFields => {
+		const problem = fieldsQuestionProblem(question);
+		if (problem !== undefined) {
+			throw new Error(`Aventara Access: ${problem}`);
+		}
+		const facts = principalFactsOf(question.principal, question.origin);
+		// The fields governed for this access: only a grant that names one opens it.
+		const governed = governedFor(file, question.resource, question.access);
+		// `"all"` stands for every field the read side does not govern (the framework's
+		// default projection, whatever the access): a write answers it only when the
+		// write side governs the same fields.
+		const allStandsFor =
+			question.access === "read" ||
+			sameFields(governed, governedFor(file, question.resource, "read"));
+		const actions: AccessAction[] =
+			question.access === "read"
+				? ["read"]
+				: question.action !== undefined
+					? [question.action]
+					: ["create", "update"];
+		const grants = [
+			...new Set(
+				actions.flatMap(
+					(action) => rulesFor(file, question.resource, action).grants,
+				),
+			),
+		];
+		const live = foldGrants(file, grants, facts).filter(
+			(grant) => grant.condition.k !== "false",
+		);
+		if (live.length === 0) {
+			return { always: [], perRow: {} };
+		}
+		const excludes = (grant: FoldedGrant, field: string): boolean =>
+			question.access === "write" &&
+			(locks.get(grant.grant)?.has(field) ?? false);
+		const names = (grant: FoldedGrant, field: string): boolean =>
+			grant.grant.fields?.includes(`${question.resource}.${field}`) ?? false;
+		const answer = (condition: Resolved): AccessWhere =>
+			condition.k === "true"
+				? {}
+				: translateWhere(nullSafe(file, question.resource, condition));
+
+		const perRow: Record<string, AccessWhere> = {};
+		for (const field of governed) {
+			const condition = orOf(
+				live
+					.filter((grant) => names(grant, field) && !excludes(grant, field))
+					.map((grant) => grant.condition),
+			);
+			if (condition.k !== "false") {
+				perRow[field] = answer(condition);
+			}
+		}
+		const excluded = new Set(
+			live.flatMap((grant) =>
+				question.access === "write" ? [...(locks.get(grant.grant) ?? [])] : [],
+			),
+		);
+		if (excluded.size === 0 && allStandsFor) {
+			return { always: "all", perRow };
+		}
+		const always: string[] = [];
+		for (const field of ownOf(file.schema, question.resource)?.fields ?? []) {
+			if (governed.includes(field)) {
+				continue;
+			}
+			if (!excluded.has(field)) {
+				always.push(field);
+				continue;
+			}
+			const condition = orOf(
+				live
+					.filter((grant) => !excludes(grant, field))
+					.map((grant) => grant.condition),
+			);
+			if (condition.k === "true") {
+				always.push(field);
+			} else if (condition.k !== "false") {
+				perRow[field] = answer(condition);
+			}
+		}
+		return { always, perRow };
+	};
+
+	const scopeOf = (question: AccessScopeQuestion): boolean | AccessWhere => {
+		const facts = principalFactsOf(question.principal, question.origin);
+		const { grants, denies } = rulesFor(
+			file,
+			question.resource,
+			question.action,
+		);
+		return translateAnswer(
+			nullSafe(
+				file,
+				question.resource,
+				scopeCondition(
+					foldGrants(file, grants, facts),
+					foldDenies(file, denies, facts),
+				),
+			),
+		);
+	};
+
+	const grantsOf = (
+		question: AccessGrantsQuestion,
+	): readonly string[] | Promise<readonly string[]> => {
+		const problem = grantsQuestionProblem(question);
+		if (problem !== undefined) {
+			throw new Error(`Aventara Access: ${problem}`);
+		}
+		const { row } = question;
+		if (typeof row !== "object" || row === null) {
+			// No row, no grant: a `can` handed this answer refuses.
+			return [];
+		}
+		const facts = principalFactsOf(question.principal, question.origin);
+		const { grants, denies } = rulesFor(file, question.resource, "update");
+		// An update deny decided on the row as it is (or on a value of the wrong type,
+		// failing closed): no grant lets the update in. A deny on a relation is the row
+		// after's to answer.
+		if (
+			foldDenies(file, denies, facts).some((deny) => {
+				const truth = evaluateOnRow(
+					file,
+					question.resource,
+					deny.condition,
+					row,
+				).k;
+				return truth === "true" || truth === "unknown";
+			})
+		) {
+			return [];
+		}
+		// Each grant's `where` and its subject's row condition, without its `after`: the
+		// condition `scopeOf` reads, asked about the row as it is. The answer lists the
+		// keys in the file's order.
+		const decided: { readonly key: string; residual: Evaluated }[] = foldGrants(
+			file,
+			grants,
+			facts,
+		).map((grant) => ({
+			key: keyOf(grant),
+			residual: evaluateOnRow(file, question.resource, grant.condition, row),
+		}));
+		const covering = (): string[] =>
+			decided.flatMap(({ key, residual }) =>
+				residual.k === "true" ? [key] : [],
+			);
+		if (
+			decided.every(
+				({ residual }) => isDecided(residual) || residual.k === "unknown",
+			)
+		) {
+			return covering();
+		}
+		return (async () => {
+			const lookups: AccessLookup[] = [];
+			for (const entry of decided) {
+				const { residual } = entry;
+				if (isDecided(residual) || residual.k === "unknown") {
+					continue;
+				}
+				const truth = await decideOnRow({
+					policies: file,
+					resource: question.resource,
+					condition: residual,
+					row,
+					kind: "existing",
+					exists: question.exists,
+					lookups,
+				});
+				// A grant that cannot be decided does not cover the row.
+				entry.residual = truth === true ? TRUE : FALSE;
+			}
+			return covering();
+		})();
+	};
+
+	return { can, grantsOf, scopeOf, fieldsOf };
+};