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

package/src/beacon/beacon.check.ts

@@ -0,0 +1,204 @@
+// The ownership beacon's check, as a service runs it when it starts: each namespace
+// whose Resources the rules read as `foreign` has one row in `_aventara_beacon`,
+// written once by that namespace's own service with a random value, and the
+// registry knows the value's hash. A database's beacons are its own, so their
+// hashes are pinned per environment, apart from `avAccess.lock.json` (which holds
+// against any registry): `avaccess pull --env <name>` writes them to
+// `avAccess.beacons.<name>.json` (`AccessBeaconPins`), or the deploy hands the same
+// object in from its environment. At startup the service reads each owner's row
+// through its own connection: the row is there and hashes to the pin only when the
+// service reaches the owner's database. Anything else (no row, another value, a
+// value that is no beacon, an owner with no pin) means the foreign facts would come
+// from somewhere the owner does not write, and the service refuses to decide.
+//
+// The check reads through an object the app hands in (`AccessBeaconReader`): the
+// engine and the generated client have no database connection of their own and
+// name no ORM. This module imports nothing and reaches no runtime API but WebCrypto's
+// digest, so `avaccess generate` copies it into a generated client as it is.
+
+/** Reads a namespace's beacon row, through the service's own connection. */
+export type AccessBeaconReader = {
+	/**
+	 * The `value` of `namespace`'s row in `_aventara_beacon`, as this service's
+	 * connection reads it; `null` when there is none.
+	 */
+	read(namespace: string): Promise<string | null>;
+};
+
+/**
+ * One environment's beacon pins, `avAccess.beacons.<environment>.json` as
+ * `avaccess pull --env <environment>` writes it: the hash of the beacon each
+ * namespace the rules read as foreign pushed from that environment's database.
+ * `format` is typed as a string so the file imported as JSON is one as it is.
+ */
+export type AccessBeaconPins = {
+	/** `"aventara-access/beacons@1"`. */
+	readonly format: string;
+	/** The namespace that reads the others: the lock's. */
+	readonly namespace: string;
+	/** The environment the pins were pulled for: `production`, `staging`, … */
+	readonly environment: string;
+	/** Each owner namespace's beacon hash, `sha256:<hex>`. */
+	readonly beacons: { readonly [namespace: string]: string };
+};
+
+/** The format marker of every beacon pins file. */
+export const BEACON_PINS_FORMAT = "aventara-access/beacons@1";
+
+/**
+ * The error a generated client throws when its beacons have not passed, shaped as
+ * `AccessError` is (`name`, `code`, a message that starts `Aventara Access:`): the
+ * client imports nothing, so it cannot throw the class itself.
+ */
+export const beaconMismatch = (
+	message: string,
+): Error & { readonly code: "ACCESS_BEACON_MISMATCH" } =>
+	Object.assign(new Error(`Aventara Access: ${message}`), {
+		name: "AccessError",
+		code: "ACCESS_BEACON_MISMATCH" as const,
+	});
+
+/** A beacon: `avb_` and 32 random bytes in base64url. */
+export const BEACON = /^avb_[A-Za-z0-9_-]{43}$/;
+
+/** A pinned beacon hash: `sha256:` and 64 lowercase hex digits. */
+export const BEACON_HASH = /^sha256:[0-9a-f]{64}$/;
+
+/** A namespace or environment name: a lowercase letter, then lowercase letters, digits, `_` or `-`. */
+const NAME = /^[a-z][a-z0-9_-]{0,62}$/;
+
+const PIN_MEMBERS = ["format", "namespace", "environment", "beacons"];
+
+/** What the check reads of WebCrypto, typed here so the module needs no DOM or Node types. */
+type Digest = {
+	readonly crypto: {
+		readonly subtle: {
+			digest(algorithm: "SHA-256", data: Uint8Array): Promise<ArrayBuffer>;
+		};
+	};
+	readonly TextEncoder: new () => { encode(text: string): Uint8Array };
+};
+
+/**
+ * A beacon's hash, as the registry and the pins name it: `sha256:<hex>` of
+ * `<namespace>:<value>`. The namespace is bound in: a value registered under one
+ * namespace never matches, or collides with, another namespace's beacon.
+ */
+export const beaconHashOf = async (
+	namespace: string,
+	value: string,
+): Promise<string> => {
+	const runtime = globalThis as unknown as Digest;
+	const digest = await runtime.crypto.subtle.digest(
+		"SHA-256",
+		new runtime.TextEncoder().encode(`${namespace}:${value}`),
+	);
+	let hex = "";
+	for (const byte of new Uint8Array(digest)) {
+		hex += byte.toString(16).padStart(2, "0");
+	}
+	return `sha256:${hex}`;
+};
+
+/**
+ * What is wrong with `pins` as `namespace`'s beacon pins of `environment` for the
+ * `owners` its rules read as foreign: its format and members, its namespace, its
+ * environment, a `sha256:` hash for every owner; `undefined` when nothing is.
+ */
+export const beaconPinsProblem = (
+	namespace: string,
+	owners: readonly string[],
+	pins: unknown,
+	environment: unknown,
+): string | undefined => {
+	if (typeof environment !== "string" || !NAME.test(environment)) {
+		return `the environment the service runs in is ${JSON.stringify(environment) ?? "missing"}, which is not an environment name (a lowercase letter, then lowercase letters, digits, "_" or "-"): name it, such as "production", and hand in that environment's pins`;
+	}
+	const file = pins as {
+		readonly [member: string]: unknown;
+		readonly beacons?: { readonly [namespace: string]: unknown };
+	} | null;
+	if (typeof file !== "object" || file === null || Array.isArray(file)) {
+		return "the beacon pins are an object, as `avaccess pull --env <environment>` writes avAccess.beacons.<environment>.json";
+	}
+	if (file.format !== BEACON_PINS_FORMAT) {
+		return `the beacon pins' format is "${BEACON_PINS_FORMAT}"; it was ${JSON.stringify(file.format) ?? "missing"}`;
+	}
+	const unknown = Object.keys(file).filter(
+		(member) => !PIN_MEMBERS.includes(member),
+	);
+	if (unknown.length > 0) {
+		return `the beacon pins have \`format\`, \`namespace\`, \`environment\` and \`beacons\`; they do not take ${unknown.map((member) => `\`${member}\``).join(", ")}`;
+	}
+	if (file.namespace !== namespace) {
+		return `the beacon pins are namespace ${JSON.stringify(file.namespace)}'s, and the rules are namespace "${namespace}"'s: pull this project's own pins with \`avaccess pull --env <environment>\``;
+	}
+	if (file.environment !== environment) {
+		return `the beacon pins are environment ${JSON.stringify(file.environment)}'s, and the service runs in environment "${environment}": hand in avAccess.beacons.${environment}.json`;
+	}
+	const beacons = file.beacons;
+	if (
+		typeof beacons !== "object" ||
+		beacons === null ||
+		Array.isArray(beacons) ||
+		Object.entries(beacons).some(
+			([owner, hash]) =>
+				!NAME.test(owner) ||
+				owner === namespace ||
+				typeof hash !== "string" ||
+				!BEACON_HASH.test(hash),
+		)
+	) {
+		return "the beacon pins' `beacons` maps each other namespace whose Resources the rules read to its beacon's `sha256:` hash";
+	}
+	const missing = owners.filter((owner) => !Object.hasOwn(beacons, owner));
+	if (missing.length > 0) {
+		return `the rules read ${missing.map((owner) => `namespace "${owner}"'s`).join(" and ")} Resources as foreign, and the beacon pins of environment "${file.environment}" hold no beacon of ${missing.length === 1 ? "it" : "them"}: pull again with \`avaccess pull --env ${file.environment} --beacon <module>\``;
+	}
+	return undefined;
+};
+
+/**
+ * What is wrong with the beacons of `owners` (the namespaces `namespace`'s rules
+ * read as foreign), held to `pins` (which must be `environment`'s) and read through
+ * `reader`; `undefined` when every
+ * owner's row is there and hashes to its pin. Each owner is read once, in order.
+ */
+export const beaconProblem = async (
+	namespace: string,
+	owners: readonly string[],
+	pins: unknown,
+	environment: unknown,
+	reader: AccessBeaconReader,
+): Promise<string | undefined> => {
+	const invalid = beaconPinsProblem(namespace, owners, pins, environment);
+	if (invalid !== undefined) {
+		return invalid;
+	}
+	if (
+		typeof reader !== "object" ||
+		reader === null ||
+		typeof reader.read !== "function"
+	) {
+		return "the beacon reader is `{ read(namespace) }`, which reads a namespace's row in _aventara_beacon through this service's own connection";
+	}
+	const { beacons } = pins as AccessBeaconPins;
+	for (const owner of [...owners].sort()) {
+		let value: unknown;
+		try {
+			value = await reader.read(owner);
+		} catch (error) {
+			return `reading namespace "${owner}"'s row in _aventara_beacon failed (${String((error as Error)?.message ?? error)}): this service cannot show it reaches "${owner}"'s database`;
+		}
+		if (value === null || value === undefined) {
+			return `this service's connection reads no row of namespace "${owner}" in _aventara_beacon, so it does not reach "${owner}"'s database: the rules read "${owner}"'s Resources as foreign, which works only within one database. Point the service at that database, or carry the fact in a JWT claim instead`;
+		}
+		if (typeof value !== "string" || !BEACON.test(value)) {
+			return `namespace "${owner}"'s row in _aventara_beacon holds no beacon (avb_ and 43 base64url characters): it was changed outside the service that writes it`;
+		}
+		if ((await beaconHashOf(owner, value)) !== beacons[owner]) {
+			return `namespace "${owner}"'s beacon, as this service's connection reads it, is not the one the beacon pins of environment "${environment}" hold: the service reaches another database than "${owner}"'s in that environment. Check that the pins are this environment's, pull them again with \`avaccess pull --env ${environment} --beacon <module>\` (it refuses while the databases differ), or carry the fact in a JWT claim instead`;
+		}
+	}
+	return undefined;
+};

package/src/canonical-json.writer.ts

@@ -0,0 +1,51 @@
+// The canonical JSON text both Access file formats hash (`policies.hash.ts`,
+// `guardrails/guardrails.hash.ts`): every object's members sorted by key (UTF-16
+// code units), whitespace removed, members whose value is `undefined` left out, and
+// strings and numbers written as `JSON.stringify` writes them (RFC 8785's rules for
+// the values these files hold). A number JSON cannot carry (NaN, Infinity) throws. Which lists a format treats as sets is the format's
+// own decision; this writer keeps every list in the order it is given.
+
+/** A JSON value, as the canonical writer reads it. */
+export type CanonicalJson =
+	| string
+	| number
+	| boolean
+	| null
+	| readonly CanonicalJson[]
+	| { readonly [key: string]: CanonicalJson | undefined };
+
+/** JSON text with every object's members sorted by key and no whitespace. */
+export const canonicalJson = (value: CanonicalJson): string => {
+	if (typeof value === "number" && !Number.isFinite(value)) {
+		// `JSON.stringify` writes NaN and Infinity as `null`: two files that decide
+		// differently would share one hash.
+		throw new Error(
+			`Aventara Access: a file holds the number ${value}, and JSON carries finite numbers only`,
+		);
+	}
+	if (value === null || typeof value !== "object") {
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${(value as readonly CanonicalJson[]).map(canonicalJson).join(",")}]`;
+	}
+	const record = value as {
+		readonly [key: string]: CanonicalJson | undefined;
+	};
+	const members = Object.keys(record)
+		.filter((key) => record[key] !== undefined)
+		.sort()
+		.map(
+			(key) =>
+				`${JSON.stringify(key)}:${canonicalJson(record[key] as CanonicalJson)}`,
+		);
+	return `{${members.join(",")}}`;
+};
+
+/** A copy of a list of names, sorted: the order of a list the format calls a set. */
+export const sortedNames = <T extends string>(list: readonly T[]): T[] =>
+	[...list].sort();
+
+/** Orders rules by their `id`. */
+export const byId = <T extends { readonly id: string }>(a: T, b: T): number =>
+	a.id < b.id ? -1 : a.id > b.id ? 1 : 0;

package/src/generator/prisma7/prisma-where.translator.ts

@@ -0,0 +1,243 @@
+// The Prisma 7 translator: the answers the decisions give, in Prisma's words. A scope
+// (`scopeOf`'s `where`, the shape the engine hands Aventara) becomes a Prisma
+// `where`, a `fieldsOf` read answer becomes a Prisma `select`, and an `exists`
+// question is asked through the service's own Prisma client. `avaccess generate
+// --orm prisma7` copies this module into the generated client beside the decisions;
+// like them, it imports nothing but them, and no Prisma module: what it builds is
+// plain data that Prisma's own input types accept.
+//
+// Each step mirrors how the framework's Prisma 7 adapter writes Aventara's `where`:
+// boolean nodes (`AND`, `OR`, `NOT`) and the scalar operators (`equals`, `not`,
+// `in`, `notIn`) keep their spelling; a to-one relation's condition is wrapped in
+// Prisma's `is`, because Prisma reads an empty unwrapped one as no condition at all;
+// a to-many relation's `some`, `every` and `none` keep theirs.
+
+import {
+	type AccessWhere,
+	defineMember,
+} from "../../aventara-where.translator.js";
+import type { AccessFields } from "../../policies.decider.js";
+import type { AccessPolicies } from "../../policies-contract.js";
+import { governedFor } from "../../scope.resolver.js";
+
+/** A Prisma `where`: plain data any `<Model>WhereInput` accepts. */
+export type PrismaWhere = { [key: string]: unknown };
+
+/** A Prisma `select` of scalar fields. */
+export type PrismaSelect = { [field: string]: true };
+
+/** What `prismaExists` needs of a model's delegate on the Prisma client. */
+export type PrismaFindFirst = {
+	findFirst(args: {
+		where: PrismaWhere;
+		select: PrismaSelect;
+	}): PromiseLike<unknown>;
+};
+
+const isWhereNode = (value: unknown): value is AccessWhere =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** A record's own member, never one it inherits. */
+const own = <T>(
+	record: { readonly [key: string]: T } | undefined,
+	key: string,
+): T | undefined =>
+	record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
+
+/**
+ * A scalar field's operators, with each `in` list copied (Prisma's lists are
+ * mutable). A bigint past a safe integer, which the file writes as its digits, is
+ * handed to Prisma as a `bigint`.
+ */
+const operatorsOf = (value: unknown, bigint: boolean): unknown => {
+	const operandOf = (operand: unknown): unknown =>
+		bigint && typeof operand === "string" ? BigInt(operand) : operand;
+	return isWhereNode(value)
+		? Object.fromEntries(
+				Object.entries(value).map(([operator, operand]) => [
+					operator,
+					Array.isArray(operand) ? operand.map(operandOf) : operandOf(operand),
+				]),
+			)
+		: value;
+};
+
+/** Aventara's `where` on a Resource of `policies`, as Prisma's `where` on its model. */
+export const toPrismaWhere = (
+	policies: AccessPolicies,
+	resource: string,
+	where: AccessWhere,
+): PrismaWhere => {
+	const facts = own(policies.schema, resource);
+	const relations = facts?.relations ?? {};
+	const translated: PrismaWhere = {};
+	for (const [key, value] of Object.entries(where)) {
+		if (key === "AND" || key === "OR") {
+			defineMember(
+				translated,
+				key,
+				(value as readonly AccessWhere[]).map((node) =>
+					toPrismaWhere(policies, resource, node),
+				),
+			);
+			continue;
+		}
+		if (key === "NOT") {
+			defineMember(
+				translated,
+				key,
+				toPrismaWhere(policies, resource, value as AccessWhere),
+			);
+			continue;
+		}
+		const relation = own(relations, key);
+		if (relation === undefined || !isWhereNode(value)) {
+			defineMember(
+				translated,
+				key,
+				operatorsOf(value, own(facts?.types, key) === "bigint"),
+			);
+			continue;
+		}
+		if (relation.cardinality === "one") {
+			defineMember(translated, key, {
+				is: toPrismaWhere(policies, relation.target, value),
+			});
+			continue;
+		}
+		defineMember(
+			translated,
+			key,
+			Object.fromEntries(
+				Object.entries(value).map(([quantifier, node]) => [
+					quantifier,
+					toPrismaWhere(policies, relation.target, node as AccessWhere),
+				]),
+			),
+		);
+	}
+	return translated;
+};
+
+/**
+ * A scope (`scopeOf`'s answer) as Prisma's `where`: every row (`{}`), no row
+ * (`{ OR: [] }`, which Prisma matches with nothing), or the translated condition.
+ */
+export const toPrismaScope = (
+	policies: AccessPolicies,
+	resource: string,
+	scope: boolean | AccessWhere,
+): PrismaWhere =>
+	scope === true
+		? {}
+		: scope === false
+			? { OR: [] }
+			: toPrismaWhere(policies, resource, scope);
+
+/**
+ * A `fieldsOf` read answer as Prisma's `select`: the Resource's scalar fields a read
+ * shows on every row. A field governed for reading is selected only when the answer
+ * opens it on every row (one governed for writing only is read as any other); a
+ * field it opens on some rows only is left out, since a `select` cannot depend on
+ * the row (ask `fieldsOf` for those). Relations are never selected: a related row
+ * would not be scoped.
+ */
+export const toPrismaSelect = (
+	policies: AccessPolicies,
+	resource: string,
+	fields: AccessFields,
+): PrismaSelect => {
+	const facts = own(policies.schema, resource);
+	const governed = governedFor(policies, resource, "read");
+	const scalars = (facts?.fields ?? []).filter(
+		(field) => own(facts?.relations, field) === undefined,
+	);
+	const select: PrismaSelect = {};
+	for (const field of scalars) {
+		const opened = own(fields.perRow, field);
+		const everyRow = opened !== undefined && Object.keys(opened).length === 0;
+		const always =
+			!governed.includes(field) &&
+			(fields.always === "all" || fields.always.includes(field));
+		if (always || everyRow) {
+			select[field] = true;
+		}
+	}
+	return select;
+};
+
+/** The property of the Prisma client that holds a model's delegate: its name, first letter lowered. */
+export const prismaDelegateOf = (resource: string): string =>
+	`${resource.charAt(0).toLowerCase()}${resource.slice(1)}`;
+
+/**
+ * Core's `exists`, through the service's Prisma client: whether a row of `resource`
+ * meets `where`, unscoped. It selects the row's first identifier and nothing else.
+ */
+export const existsThroughPrisma = async (
+	client: object,
+	policies: AccessPolicies,
+	resource: string,
+	where: AccessWhere,
+): Promise<boolean> => {
+	const delegateName = prismaDelegateOf(resource);
+	const delegate = (client as { readonly [name: string]: unknown })[
+		delegateName
+	] as PrismaFindFirst | undefined;
+	if (delegate === undefined || typeof delegate.findFirst !== "function") {
+		throw new Error(
+			`Aventara Access: the rules ask whether a ${resource} row exists, and the Prisma client has no \`${delegateName}\`: add the model ${resource} to the Prisma schema this service queries`,
+		);
+	}
+	const facts = own(policies.schema, resource);
+	const identifier = facts?.identifiers[0] ?? facts?.fields.slice(0, 1) ?? [];
+	const select: PrismaSelect = {};
+	for (const field of identifier) {
+		select[field] = true;
+	}
+	const found = await delegate.findFirst({
+		where: toPrismaWhere(policies, resource, where),
+		select,
+	});
+	return found !== null && found !== undefined;
+};
+
+/**
+ * The Prisma client the ownership beacon is read and written through: a model over
+ * the `_aventara_beacon` table, keyed by the namespace,
+ * `model AventaraBeacon { id String @id  namespace String @unique  value String  createdAt DateTime @default(now())  @@map("_aventara_beacon") }`.
+ */
+export type PrismaBeaconClient = {
+	readonly aventaraBeacon: {
+		findUnique(args: {
+			where: { namespace: string };
+			select: { value: true };
+		}): PromiseLike<unknown>;
+		create(args: {
+			data: { namespace: string; value: string };
+		}): PromiseLike<unknown>;
+	};
+};
+
+/**
+ * The beacon store over the service's Prisma client: `read` a namespace's row in
+ * `_aventara_beacon`, `create` one. What `avaccess push --beacon` and `pull --beacon`
+ * load, and what the client's `checkBeacons` reads through.
+ */
+export const beaconThroughPrisma = (
+	client: PrismaBeaconClient,
+): {
+	read(namespace: string): Promise<string | null>;
+	create(namespace: string, value: string): Promise<void>;
+} => ({
+	read: async (namespace) => {
+		const row = (await client.aventaraBeacon.findUnique({
+			where: { namespace },
+			select: { value: true },
+		})) as { readonly value?: unknown } | null | undefined;
+		return typeof row?.value === "string" ? row.value : null;
+	},
+	create: async (namespace, value) => {
+		await client.aventaraBeacon.create({ data: { namespace, value } });
+	},
+});