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

package/dist/foreign-references.check.js

@@ -0,0 +1,131 @@
+// A check of the rules against the framework that hosts them: a role that may
+// create or update a row holding a reference (a to-one relation's reference fields)
+// to a foreign Resource, with no condition of the write grant through that
+// relation. A foreign Resource is read in conditions and never granted on, so the
+// engine lists it in `unheld` and Aventara holds no written reference to it to the
+// caller's read scope (which is `false` for every caller there): the write grant
+// alone decides which row may be linked. A grant that reads nothing through the
+// relation lets the caller link any row of the foreign Resource by its identifier.
+//
+// A grant constrains the link when one of the conditions checked on the row the
+// write leaves reads the relation: on a create, its `where`, its `in`, and the row
+// condition of a subject role held on the writing Resource; on an update, those and
+// its `after` (an update grant's `where` is checked on the row it leaves too). A
+// condition reads the relation when it filters through it (`{ campaign: { … } }`)
+// or compares its reference field with `equals` or `in` (`{ campaignId: me.id }`),
+// itself or in every branch of an `OR` or any part of an `AND`; one under a `NOT`,
+// or a `not` / `notIn` comparison, excludes rows and leaves every other one
+// linkable. "Constrains" says nothing of whether the condition is the right one:
+// it only finds the grants that check nothing.
+//
+// It runs when the framework hosts the engine (`hosted({ held })`), as
+// ACCESS_REFERENCE_UNREADABLE does, for the writing Resources the framework serves
+// (`held`). It warns and never refuses: the engine answers exactly as before. Not
+// warned about: a reference the grant's `write.except` locks.
+import { emitAccessWarning, listed } from "./access-warning.emitter.js";
+import { ownOf } from "./scope.resolver.js";
+const WARNING_CODE = "ACCESS_FOREIGN_REFERENCE_UNCHECKED";
+/** Whether `predicate`, holding on a row, limits which row its `relation` links. */
+const constrains = (predicate, relation, fields) => {
+    if (predicate === undefined) {
+        return false;
+    }
+    switch (predicate.op) {
+        case "false":
+            return true;
+        case "and":
+            return predicate.args.some((arg) => constrains(arg, relation, fields));
+        case "or":
+            return (predicate.args.length > 0 &&
+                predicate.args.every((arg) => constrains(arg, relation, fields)));
+        case "cmp":
+            return (fields.includes(predicate.field) &&
+                (predicate.cmp === "eq" || predicate.cmp === "in"));
+        case "rel":
+            return predicate.relation === relation && predicate.where.op !== "true";
+        default:
+            return false;
+    }
+};
+/** The row condition of `subject` when it is a role held on rows of `resource`. */
+const subjectRowCondition = (policies, subject, resource) => {
+    const definition = ownOf(policies.roles, subject);
+    return definition !== undefined &&
+        "on" in definition &&
+        definition.on === resource
+        ? definition.where
+        : undefined;
+};
+/** Whether `grant`, for `subject`, constrains the link `relation` makes on `action`. */
+const grantConstrains = (policies, grant, subject, resource, action, relation, fields) => grant.in === relation ||
+    constrains(grant.where, relation, fields) ||
+    (action === "update" && constrains(grant.after, relation, fields)) ||
+    constrains(subjectRowCondition(policies, subject, resource), relation, fields);
+/**
+ * The warnings for `policies` hosted by a framework that serves the Resources in
+ * `held`, one per writing role and foreign target, each naming every reference
+ * that role may write to it unconstrained.
+ */
+const foreignReferenceWarnings = (policies, held) => {
+    const found = new Map();
+    for (const grant of policies.grants) {
+        const actions = grant.actions.filter((action) => action === "create" || action === "update");
+        if (actions.length === 0) {
+            continue;
+        }
+        const locked = new Set(grant.write?.except ?? []);
+        const resources = grant.resource === "*" ? Object.keys(policies.schema) : [grant.resource];
+        for (const resource of resources) {
+            const facts = ownOf(policies.schema, resource);
+            if (facts === undefined ||
+                facts.foreign !== undefined ||
+                !held.has(resource)) {
+                continue;
+            }
+            for (const [relation, fact] of Object.entries(facts.relations)) {
+                const fields = fact.referenceFields;
+                const owner = ownOf(policies.schema, fact.target)?.foreign;
+                if (owner === undefined ||
+                    fact.cardinality !== "one" ||
+                    fields === undefined ||
+                    locked.has(relation) ||
+                    fields.some((field) => locked.has(field))) {
+                    continue;
+                }
+                for (const writer of grant.subjects) {
+                    if (actions.every((action) => grantConstrains(policies, grant, writer, resource, action, relation, fields))) {
+                        continue;
+                    }
+                    const key = `${writer}\u0000${fact.target}`;
+                    const entry = found.get(key) ?? {
+                        writer,
+                        target: fact.target,
+                        owner,
+                        relation,
+                        references: [],
+                    };
+                    for (const field of fields) {
+                        const name = `${resource}.${field}`;
+                        if (!entry.references.includes(name)) {
+                            entry.references.push(name);
+                        }
+                    }
+                    found.set(key, entry);
+                }
+            }
+        }
+    }
+    return [...found.values()].map(({ writer, target, owner, relation, references }) => {
+        const one = references.length === 1;
+        return `${writer} may write ${listed(references)}, ${one ? "a reference" : "references"} to Resource "${target}", which namespace "${owner}" owns (foreign), and no condition of the write grant reads that relation, so any row of "${target}" can be linked by its identifier. Aventara does not hold a reference to a foreign Resource to what the caller may read: the write grant decides which row may be linked. Constrain it through the relation (a \`where\` on a create grant, an \`after\` on an update grant, e.g. \`{ ${relation}: { … } }\`), or leave the reference out of the write (\`write: { except: [...] }\`).`;
+    });
+};
+/**
+ * Emits `policies`' warnings under a framework that serves the Resources in
+ * `held`, each once per process and namespace.
+ */
+export const warnForeignReferences = (policies, held) => {
+    for (const message of foreignReferenceWarnings(policies, held)) {
+        emitAccessWarning(WARNING_CODE, policies.namespace, message);
+    }
+};

package/dist/generator/client.emitter.d.ts

@@ -0,0 +1,28 @@
+import type { AccessLock } from "../lock/lock-contract.js";
+import type { AccessDenyRule, AccessPolicies } from "../policies-contract.js";
+import type { ClientTranslator } from "./orm.translator.js";
+/** What a generated client is made from. */
+type ClientInput = {
+    /** The pulled policies file, checked and held to the lock. */
+    readonly policies: AccessPolicies;
+    /** The denies the org's pulled guardrails add to it, composed from both files' canonical forms (none when the lock pins none). */
+    readonly guardrailDenies: readonly AccessDenyRule[];
+    readonly lock: AccessLock;
+    readonly translator: ClientTranslator;
+    /** The command that regenerates the file, as the banner prints it. */
+    readonly command: string;
+    /** The `@aventara/access` version whose decisions the file carries. */
+    readonly version: string;
+    /** How `avAccess.ts` names `avAccess.internal.ts`: `./avAccess.internal.js`, as the project's tsconfig asks. */
+    readonly internalSpecifier: string;
+};
+/** The two files of a generated client. */
+type ClientFiles = {
+    /** `avAccess.ts`: `access` and the client's types. */
+    readonly client: string;
+    /** `avAccess.internal.ts`: the copied decisions and translator. */
+    readonly internal: string;
+};
+/** The generated client's two files. */
+export declare const emitClient: (input: ClientInput) => Promise<ClientFiles>;
+export {};

package/dist/generator/client.emitter.js

@@ -0,0 +1,411 @@
+// The generated client's text: two TypeScript files a service that does not run on
+// Aventara decides with, and nothing else of Access.
+//
+// - `avAccess.ts`, the file the service imports: the banner (generated, do not edit,
+//   the command that regenerates it, the pinned files), the namespace's Resource
+//   types, the pulled policies file as a constant with the guardrails' denies beside
+//   it, then `access`: `can`, `scopeOf`, `fieldsOf` (ORM-neutral, answering in
+//   Aventara's `where`), `checkBeacons` and the translator's functions. It exports
+//   `access` and the client's types only. When the rules read other namespaces'
+//   Resources as foreign, `access` decides nothing until
+//   `access.checkBeacons(reader, pins)` has passed at startup.
+// - `avAccess.internal.ts` beside it: the banner, then the copied decision modules
+//   and the translator's module, as they are. Their names stay exported there (the
+//   client imports them, and a declaration nothing reads would fail
+//   `noUnusedLocals`), and none of them is reachable from `avAccess.ts`.
+//
+// The texts are a function of their input alone: the same pulled files, translator,
+// command, package version and import spelling give the same bytes. Every list they
+// write is sorted, and the policies file is written in its canonical member order.
+import { foreignOwnersOf } from "../lock/lock.verifier.js";
+import { canonicalPolicies } from "../policies.hash.js";
+import { DECISION_MODULES, readCopiedModules, } from "./copied-modules.reader.js";
+import { namespaceFactsOf, propertyKey, } from "./namespace.facts.js";
+import { typescriptLiteral } from "./typescript-literal.writer.js";
+/** What the client file reads from the internal one, besides the translator's names. */
+const DECISION_IMPORTS = {
+    values: [
+        "beaconMismatch",
+        "beaconProblem",
+        "createDecider",
+        "grantsQuestionProblem",
+        "newTrace",
+    ],
+    types: [
+        "AccessAction",
+        "AccessBeaconPins",
+        "AccessBeaconReader",
+        "AccessCanQuestion",
+        "AccessDenyRule",
+        "AccessFields",
+        "AccessGrantsQuestion",
+        "AccessOrigin",
+        "AccessPolicies",
+        "AccessWhere",
+    ],
+};
+const RULE = "// ---------------------------------------------------------------------------";
+const section = (title) => `${RULE}\n// ${title}\n${RULE}`;
+/** What ends a comment's line: control characters and the line separators. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the characters it removes
+const BREAKS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+/**
+ * Text from the project (a path, the command line) as a comment carries it: no line
+ * break, which would end a `//` comment, and no star followed by a slash, which
+ * would end a block comment, so nothing in it becomes code.
+ */
+const inComment = (text) => text.replace(BREAKS, " ").replace(/\*\//g, "*\\/");
+const banner = (input, file) => {
+    const { lock } = input;
+    const pins = [
+        `//     ${inComment(lock.policies.path)}  ${lock.policies.hash}`,
+        lock.guardrails === null
+            ? "//     (the lock pins no guardrails)"
+            : `//     ${inComment(lock.guardrails.path)}  ${lock.guardrails.hash}`,
+    ];
+    return [
+        "// biome-ignore-all format: generated output",
+        "// biome-ignore-all lint: generated output",
+        "/* eslint-disable */",
+        `// Generated by \`avaccess generate\` (@aventara/access ${input.version}). Do not edit this`,
+        "// file: change the rules where they are authored, push them, pull them, and",
+        "// regenerate it with",
+        "//",
+        `//     ${inComment(input.command)}`,
+        "//",
+        `// Namespace ${JSON.stringify(lock.namespace)}, from avAccess.lock.json:`,
+        ...pins,
+        "//",
+        ...(file === "client"
+            ? [
+                "// It decides from the pulled files with a copy of Access's decisions, kept in",
+                `// ${JSON.stringify(input.internalSpecifier)} beside it, and imports nothing else: no @aventara`,
+                `// package and no ${input.translator.title ?? "ORM"} module. The scope covers the queries you pass it`,
+                "// to, and only those.",
+            ]
+            : [
+                "// The copy of Access's decisions and translator the client beside it imports.",
+                "// Import `access` and its types from the client; nothing here is its API.",
+            ]),
+    ].join("\n");
+};
+const rowTypes = (namespace) => {
+    const known = new Set(namespace.resources.map((resource) => resource.name));
+    const rows = namespace.resources.map((resource) => {
+        const members = [
+            ...resource.fields.map((field) => `\t\treadonly ${propertyKey(field)}?: unknown;`),
+            // A relation to a Resource the file does not list (a trimmed model) is typed
+            // `unknown`: there is no row type to name.
+            ...resource.relations.map((relation) => `\t\treadonly ${propertyKey(relation.name)}?: ${!known.has(relation.target)
+                ? "unknown"
+                : relation.cardinality === "one"
+                    ? `ResourceRows[${JSON.stringify(relation.target)}] | null`
+                    : `readonly ResourceRows[${JSON.stringify(relation.target)}][]`};`),
+        ];
+        return `\treadonly ${propertyKey(resource.name)}: {\n${members.join("\n")}\n\t};`;
+    });
+    const fields = namespace.resources.map((resource) => `\treadonly ${propertyKey(resource.name)}: ${resource.fields.length === 0
+        ? "never"
+        : resource.fields.map((field) => JSON.stringify(field)).join(" | ")};`);
+    const names = namespace.resources
+        .map((resource) => JSON.stringify(resource.name))
+        .join(" | ");
+    return `/** The Resources the rules name: the namespace's own, and the ones they read from another namespace. */
+export type ResourceName = ${names === "" ? "never" : names};
+
+/**
+ * A row of each Resource as \`can\` reads it: any of its fields. A relation on it is
+ * accepted, so a row your ORM returns fits, and never read: a relation condition is
+ * asked through \`exists\`. Never put relation data a client sent on a row. The
+ * policies file names fields, not their types, so each is \`unknown\`.
+ */
+export type ResourceRows = {
+${rows.join("\n")}
+};
+
+/** The scalar fields of each Resource. */
+export type ResourceFields = {
+${fields.join("\n")}
+};`;
+};
+const API = `/** Who asks about one of the namespace's Resources, and through which layer. */
+export type QuestionOf<R extends ResourceName> = {
+	/** Your principal: an object the rules read (\`me.<path>\`, its \`claims\`), or \`null\` for anyone signed out. */
+	readonly principal: unknown;
+	/** The layer the request came through: \`"client"\` for a user's request, \`"agent"\` for an AI agent's, \`"application"\` for the service's own. */
+	readonly origin: AccessOrigin;
+	readonly resource: R;
+};
+
+/** \`can\`: without a row, whether the principal could ever do \`action\`; with one, whether it may on this row. */
+export type CanQuestionOf<R extends ResourceName> = QuestionOf<R> &
+	(
+		| {
+				readonly action: "update";
+				/**
+				 * On an update with a \`row\` only: what \`grantsOf\` answered about the row before
+				 * the update, asked before you wrote it. The grant that covers \`row\` must then be
+				 * one of these. With \`before\` too, each one's \`where\` is checked on it in memory;
+				 * a relation condition on it is not asked again, so it is the one the database
+				 * held before the update.
+				 */
+				readonly beforeGrants?: readonly string[];
+		  }
+		| {
+				readonly action: Exclude<AccessAction, "update">;
+				/** An update's only. */
+				readonly beforeGrants?: undefined;
+		  }
+	) & {
+	/**
+	 * The row a create inserts, an update leaves, or a read or delete is about. For an
+	 * update, limit the update itself to the rows \`scopeOf({ action: "update" })\`
+	 * returns.
+	 */
+	readonly row?: ResourceRows[R];
+	/**
+	 * 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, so no update moves a row from the rows one
+	 * grant reaches to another's. Without it, \`can\` checks only the row the update
+	 * leaves.
+	 */
+	readonly before?: ResourceRows[R];
+	/** Whether a row of \`resource\` meets \`where\`, unscoped: what \`row\` does not carry is asked through it. */
+	readonly exists?: (
+		resource: ResourceName,
+		where: AccessWhere,
+	) => Promise<boolean>;
+};
+
+/** \`grantsOf\`: the update grants that cover \`row\`, the row you are about to update, as it is now. */
+export type GrantsQuestionOf<R extends ResourceName> = QuestionOf<R> & {
+	readonly action: "update";
+	readonly row: ResourceRows[R];
+	/** Whether a row of \`resource\` meets \`where\`, unscoped: what \`row\` does not carry is asked through it. */
+	readonly exists?: (
+		resource: ResourceName,
+		where: AccessWhere,
+	) => Promise<boolean>;
+};
+
+/** \`scopeOf\`: the rows the principal may read, update or delete. */
+export type ScopeQuestionOf<R extends ResourceName> = QuestionOf<R> & {
+	readonly action: "read" | "update" | "delete";
+};
+
+/** \`fieldsOf\`: the fields the principal may read, or write by one action. */
+export type FieldsQuestionOf<R extends ResourceName> = QuestionOf<R> &
+	(
+		| { readonly access: "read" }
+		| { readonly access: "write"; readonly action?: "create" | "update" }
+	);
+
+/** Whether the principal may do \`action\`; on \`row\` when one is given. Default deny, any grant allows, any deny wins. */
+const can = <R extends ResourceName>(
+	question: CanQuestionOf<R>,
+): boolean | Promise<boolean> =>
+	decider.can(question as AccessCanQuestion, newTrace());
+
+/**
+ * The update grants that cover \`row\` before you update it: opaque keys, no rule data.
+ * Ask it before the write, in the update's transaction, and pass the answer to \`can\`
+ * as \`beforeGrants\` with the row the update leaves.
+ */
+const grantsOf = <R extends ResourceName>(
+	question: GrantsQuestionOf<R>,
+): readonly string[] | Promise<readonly string[]> =>
+	decider.grantsOf(question as AccessGrantsQuestion);
+
+/** The rows the principal may \`action\`: every row (\`true\`), none (\`false\`), or the rows a \`where\` matches. */
+const scopeOf = <R extends ResourceName>(
+	question: ScopeQuestionOf<R>,
+): boolean | AccessWhere => decider.scopeOf(question);
+
+/** The fields usable on every reachable row (\`always\`), and those usable on some rows only (\`perRow\`, with their \`where\`). */
+const fieldsOf = <R extends ResourceName>(
+	question: FieldsQuestionOf<R>,
+): AccessFields => decider.fieldsOf(question);
+
+/**
+ * The startup check that this service reaches the database of each namespace whose
+ * Resources the rules read as foreign: its row in \`_aventara_beacon\`, read through
+ * \`reader\` (this service's own connection), hashes to its pin in \`pins\`, the pins of
+ * \`environment\` (avAccess.beacons.<environment>.json). Await it before the service
+ * takes requests: while the rules read another namespace, \`access\` answers nothing
+ * until it has passed, and nothing once a check has failed, for good (an error with
+ * \`code: "ACCESS_BEACON_MISMATCH"\`); calls run one after another. With none read it
+ * passes at once.
+ */
+const checkBeacons = (
+	reader: AccessBeaconReader,
+	pins: AccessBeaconPins,
+	environment: string,
+): Promise<void> => {
+	const run = async (): Promise<void> => {
+		if (foreignOwners.length === 0) {
+			return;
+		}
+		if (failed !== undefined) {
+			throw beaconMismatch(
+				\`a beacon check failed before, and the client stays shut: \${failed}\`,
+			);
+		}
+		const problem = await beaconProblem(
+			pulledPolicies.namespace ?? "",
+			foreignOwners,
+			pins,
+			environment,
+			reader,
+		);
+		if (problem !== undefined) {
+			failed = problem;
+			refusal = problem;
+			throw beaconMismatch(problem);
+		}
+		refusal = undefined;
+	};
+	const result = checking.then(run);
+	checking = result.catch(() => undefined);
+	return result;
+};`;
+const copied = (modules) => modules
+    .map((module) => `${section(`${module.path.replace(/^src\//, "")}, from @aventara/access`)}\n\n${module.text}`)
+    .join("\n");
+/** The client file's one import, and its re-export of the translator's types. */
+const imports = (input, ormPart) => {
+    const entries = [];
+    // Sorted by name, case aside (as Biome's import organizer sorts them), so a
+    // project that formats generated files finds nothing to change.
+    for (const part of [DECISION_IMPORTS, ormPart.imports]) {
+        for (const name of part.values) {
+            entries.push(`${name.toLowerCase()} ${name}`);
+        }
+        for (const name of part.types) {
+            entries.push(`${name.toLowerCase()} type ${name}`);
+        }
+    }
+    entries.sort();
+    let list = "";
+    for (const entry of entries) {
+        list += `\t${entry.slice(entry.indexOf(" ") + 1)},\n`;
+    }
+    const specifier = JSON.stringify(input.internalSpecifier);
+    const reexport = ormPart.exports.length === 0
+        ? ""
+        : `\n\nexport type { ${[...ormPart.exports].sort().join(", ")} } from ${specifier};`;
+    return `import {\n${list}} from ${specifier};${reexport}`;
+};
+/** The generated client's two files. */
+export const emitClient = async (input) => {
+    const modules = await readCopiedModules([
+        ...DECISION_MODULES,
+        ...input.translator.modules,
+    ]);
+    const namespace = namespaceFactsOf(input.lock.namespace, input.policies);
+    const ormPart = input.translator.clientPart(namespace);
+    const pulled = JSON.parse(canonicalPolicies(input.policies));
+    const members = [
+        "can",
+        "grantsOf",
+        "scopeOf",
+        "fieldsOf",
+        "checkBeacons",
+        ...ormPart.members,
+    ];
+    const internal = `${banner(input, "internal")}
+
+${copied(modules)}`;
+    const client = `${banner(input, "client")}
+
+${imports(input, ormPart)}
+
+${section(`Namespace ${JSON.stringify(namespace.namespace)}`)}
+
+${rowTypes(namespace)}
+
+/** The namespace's policies file, as \`avaccess pull\` wrote it (${inComment(input.lock.policies.path)}). */
+const pulledPolicies: AccessPolicies = ${typescriptLiteral(pulled)};
+
+/** The denies the org's guardrails add to the namespace's rules${input.lock.guardrails === null ? " (the lock pins none)" : ` (${inComment(input.lock.guardrails.path)})`}. */
+const guardrailDenies: readonly AccessDenyRule[] = ${typescriptLiteral(input.guardrailDenies)};
+
+/** The file the decisions run from: the namespace's rules, narrowed by the guardrails. */
+const policies: AccessPolicies = {
+	...pulledPolicies,
+	denies: [...pulledPolicies.denies, ...guardrailDenies],
+};
+
+/**
+ * The namespaces whose Resources the rules read as foreign: \`checkBeacons\` holds each
+ * one's row in \`_aventara_beacon\`, read through this service's connection, to its pin.
+ */
+const foreignOwners: readonly string[] = ${typescriptLiteral(foreignOwnersOf(input.policies))};
+
+/** Why the client answers nothing yet: \`undefined\` once the beacons have passed, or when the rules read no other namespace. */
+let refusal: string | undefined =
+	foreignOwners.length === 0
+		? undefined
+		: "the rules read other namespaces' Resources as foreign, and the beacons were not checked: \`await access.checkBeacons(reader, pins, environment)\` when the service starts, before it takes requests, with this environment's avAccess.beacons.<environment>.json";
+
+/** A failed beacon check: no later check opens the client again. */
+let failed: string | undefined;
+
+/** The beacon checks, one after another. */
+let checking: Promise<void> = Promise.resolve();
+
+const open = (): void => {
+	if (refusal !== undefined) {
+		throw beaconMismatch(refusal);
+	}
+};
+
+const decided = createDecider(policies);
+
+/** The decisions, each refused while the beacons the lock pins have not passed. */
+const decider: typeof decided = {
+	...decided,
+	can: (question, trace) => {
+		open();
+		return decided.can(question, trace);
+	},
+	grantsOf: (question) => {
+		open();
+		const problem = grantsQuestionProblem(question);
+		if (problem !== undefined) {
+			// Shaped as the engine's \`AccessError\`: the client imports nothing.
+			throw Object.assign(new Error(\`Aventara Access: \${problem}\`), {
+				name: "AccessError",
+				code: "ACCESS_QUESTION_INVALID" as const,
+			});
+		}
+		return decided.grantsOf(question);
+	},
+	scopeOf: (question) => {
+		open();
+		return decided.scopeOf(question);
+	},
+	fieldsOf: (question) => {
+		open();
+		return decided.fieldsOf(question);
+	},
+};
+
+${section("Decisions")}
+
+${API}
+
+${input.translator.title === undefined
+        ? ""
+        : `${section(`The ${input.translator.title} translator`)}
+
+${ormPart.text}
+`}/** Access's decisions for namespace ${JSON.stringify(namespace.namespace)}, ${input.translator.title === undefined
+        ? "answering in Aventara's `where`"
+        : `with the ${input.translator.title} translator`}. */
+export const access = {
+${members.map((member) => `\t${member},`).join("\n")}
+};
+`;
+    return { client, internal };
+};

package/dist/generator/copied-modules.reader.d.ts

@@ -0,0 +1,14 @@
+/** The decision modules every generated client carries, in an order that defines each name before it is read. */
+export declare const DECISION_MODULES: readonly string[];
+/** One module's text as the generated client carries it. */
+export type CopiedModule = {
+    /** Its path in the package, `src/scope.resolver.ts`. */
+    readonly path: string;
+    /** Its declarations: the text without its header comment and its imports. */
+    readonly text: string;
+};
+/**
+ * Reads `paths` (package paths, in order) as the generated client carries them.
+ * Throws when a module imports something that is not among `paths` before it.
+ */
+export declare const readCopiedModules: (paths: readonly string[]) => Promise<readonly CopiedModule[]>;

package/dist/generator/copied-modules.reader.js

@@ -0,0 +1,80 @@
+// The modules `avaccess generate` copies into a generated client, read from the
+// package's own TypeScript sources: the policies file's types, the principal fold,
+// Aventara's `where`, the row evaluator and the decisions, then the chosen ORM
+// translator's module. One source: the engine runs these modules, and the generated
+// client carries a copy of the same text, so the two decide alike.
+//
+// The package ships these sources beside `dist/` (its `files`), and this reader finds
+// them two directories up from itself, which is the package's root from `src/generator/`
+// and from `dist/generator/` alike. Each module's header comment and imports are left
+// out of the copy; an import of anything but another copied module is refused, so a
+// copied module can never pull a dependency into a service's generated file.
+import { readFile } from "node:fs/promises";
+/** The decision modules every generated client carries, in an order that defines each name before it is read. */
+export const DECISION_MODULES = [
+    "src/policies-contract.ts",
+    "src/scope.resolver.ts",
+    "src/aventara-where.translator.ts",
+    "src/predicate.evaluator.ts",
+    "src/canonical-json.writer.ts",
+    "src/sha256.digest.ts",
+    "src/policies.decider.ts",
+    "src/beacon/beacon.check.ts",
+];
+const IMPORT = /^import\s[^;]*?\sfrom\s+"([^"]+)";\n/gm;
+/** Any other way to load a module: a re-export, an import left over, `import()`, `require`. */
+const LEFT_IMPORT = /^\s*(?:import|export)\s[^;]*?\sfrom\s+"|^\s*import\s+"|\bimport\s*\(|\brequire\s*\(/m;
+/** The package's root: `src/generator/` and `dist/generator/` are both two levels below it. */
+const packageFile = (path) => decodeURIComponent(new URL(`../../${path}`, import.meta.url).pathname);
+/** The package path an import names, from the module at `from`; `undefined` when it leaves the package's sources. */
+const resolveImport = (from, specifier) => {
+    if (!specifier.startsWith("./") && !specifier.startsWith("../")) {
+        return undefined;
+    }
+    const parts = from.split("/").slice(0, -1);
+    for (const part of specifier.split("/")) {
+        if (part === "..") {
+            parts.pop();
+        }
+        else if (part !== ".") {
+            parts.push(part);
+        }
+    }
+    return parts.join("/").replace(/\.js$/, ".ts");
+};
+/** The header comment: the comment lines, and the blank lines, before the first line of code. */
+const withoutHeader = (text) => {
+    const lines = text.split("\n");
+    let first = 0;
+    while (first < lines.length &&
+        ((lines[first] ?? "").startsWith("//") || (lines[first] ?? "") === "")) {
+        first += 1;
+    }
+    return lines.slice(first).join("\n");
+};
+/**
+ * Reads `paths` (package paths, in order) as the generated client carries them.
+ * Throws when a module imports something that is not among `paths` before it.
+ */
+export const readCopiedModules = async (paths) => {
+    const modules = [];
+    for (const [index, path] of paths.entries()) {
+        const source = await readFile(packageFile(path), "utf8");
+        const earlier = new Set(paths.slice(0, index));
+        const text = withoutHeader(source)
+            .replace(IMPORT, (_statement, specifier) => {
+            const target = resolveImport(path, specifier);
+            if (target === undefined || !earlier.has(target)) {
+                throw new Error(`Aventara Access: ${path} imports ${JSON.stringify(specifier)}, and a module copied into a generated client imports only the copied modules before it (${[...earlier].join(", ") || "none"})`);
+            }
+            return "";
+        })
+            .replace(/^\n+/, "")
+            .replace(/\n+$/, "\n");
+        if (LEFT_IMPORT.test(text)) {
+            throw new Error(`Aventara Access: ${path} loads a module in a form the generator does not copy (a re-export, \`import()\` or \`require\`); a module copied into a generated client imports only the copied modules before it`);
+        }
+        modules.push({ path, text });
+    }
+    return modules;
+};