@aventara/core 1.0.0-rc.3 → 1.0.0-rc.4

package/dist/policy/policy-condition.js

@@ -0,0 +1,36 @@
+export function allOf(left, right) {
+    if (left === false || right === false) {
+        return false;
+    }
+    if (left === true) {
+        return right;
+    }
+    if (right === true) {
+        return left;
+    }
+    return { AND: [left, right] };
+}
+export function anyOf(left, right) {
+    if (left === true || right === true) {
+        return true;
+    }
+    if (left === false) {
+        return right;
+    }
+    if (right === false) {
+        return left;
+    }
+    return { OR: [left, right] };
+}
+export function everyOf(conditions) {
+    return conditions.reduce(allOf, true);
+}
+export function someOf(conditions) {
+    return conditions.reduce(anyOf, false);
+}
+export function noneOf(condition) {
+    return typeof condition === "boolean" ? !condition : { NOT: condition };
+}
+export function whereOf(condition) {
+    return condition === true ? {} : condition;
+}

package/dist/policy/policy-engine.d.ts

@@ -0,0 +1,111 @@
+import type { AvRequestOrigin } from "../config/config-layer.js";
+/** An answer now or later: every question may be answered asynchronously. */
+type PolicyAnswer<T> = T | Promise<T>;
+/**
+ * A fragment of Aventara's own `where` grammar, as a policy states a row
+ * condition: a scope, a field's per-row grant, or the question an engine's rule
+ * asks through `exists`. It is validated against the Core Contract when it is
+ * used, never the caller's, so it may name a field the caller cannot see
+ * (`ownerId`). One that does not validate is the server's defect: the request
+ * answers `A3000`.
+ */
+export type AvPolicyWhere = {
+    readonly [key: string]: unknown;
+};
+/** What every question to the engine states. */
+type PolicyQuestion = {
+    /** What the configuration's `policy.principal` derived for the request, or the `as` of an application call. */
+    readonly principal: unknown;
+    /** Which layer the request runs under. */
+    readonly origin: AvRequestOrigin;
+    /** The Resource the question is about. */
+    readonly resource: string;
+};
+/**
+ * The policy engine a Framework consults (root configuration `policy.engine`).
+ * Core asks it three questions per request and Resource, and enforces the
+ * answers: the operation (`can`), the rows (`scopeOf`) and the fields
+ * (`fieldsOf`). Every method may answer with a promise.
+ *
+ * `Governed` is the engine's `governed` set, stated by its type so the
+ * application's types leave those fields out of every default projection, as
+ * the Contracts do.
+ */
+export interface AvPolicyEngine<Governed extends {
+    readonly [resource: string]: readonly string[];
+} = {
+    readonly [resource: string]: readonly string[];
+}> {
+    /**
+     * The fields and relations the policy governs, by Resource. Each is left out
+     * of every default projection, for every caller, and is the only trace the
+     * policy leaves in a Contract (a `governed: true` mark). A caller that wants
+     * one names it, and is refused (`A4002`) unless it may read it on every row
+     * it uses it on. Checked against the Core Contract at startup.
+     */
+    readonly governed?: Governed;
+    /**
+     * The relation paths and filter operators the engine's rules filter on, by
+     * the rule's name, each path a list of segments:
+     * `["Note", "campaign", "memberships", "some", "userId", "equals"]`, a
+     * Resource, then its fields and relations (a to-many relation followed by
+     * `some`, `every` or `none`), then the scalar field, then optionally the
+     * filter operator. Checked against the Core Contract at startup: a path it
+     * cannot filter fails construction, naming the rule.
+     */
+    readonly paths?: {
+        readonly [rule: string]: readonly (readonly string[])[];
+    };
+    /**
+     * The writes whose grants carry an `after` condition, by Resource: a row
+     * they change must still meet it once changed (`{ Note: ["update"] }`).
+     * Inside a transaction core asks `can` about each row every checked update
+     * changed, listed or not, and rolls the write back (`A4002`) when one fails.
+     * This list decides where the operation has no interactive transaction:
+     * these updates are refused there (`A4002`), and every other one runs
+     * without the after check. Checked against the Core Contract at startup.
+     */
+    readonly afterChecks?: {
+        readonly [resource: string]: readonly "update"[];
+    };
+    /**
+     * Whether the principal may run `action` on `resource`. Asked once per
+     * request before any developer stage, without a row: `false` refuses the
+     * request (`A4002`). Asked again with the row a write leaves: each row a
+     * create inserts (before the insert), and each row an update changed (after
+     * the write, inside its transaction; see `afterChecks`); `false` refuses the
+     * write. Rules that need a fact the row does not carry ask it
+     * through `exists`, which core runs through the adapter, unscoped, inside
+     * the write's transaction when it has one, and answers with a boolean only.
+     */
+    can(question: PolicyQuestion & {
+        readonly action: "read" | "create" | "update" | "delete";
+        readonly row?: Readonly<Record<string, unknown>>;
+        readonly exists: (resource: string, where: AvPolicyWhere) => Promise<boolean>;
+    }): PolicyAnswer<boolean>;
+    /**
+     * The rows the principal may `action`: `true` every row, `false` none, or a
+     * condition core ANDs into the request at every level that reads the
+     * Resource (its `where`, an included relation's, a relation filter, a
+     * relation count).
+     */
+    scopeOf(question: PolicyQuestion & {
+        readonly action: "read" | "update" | "delete";
+    }): PolicyAnswer<boolean | AvPolicyWhere>;
+    /**
+     * The fields the principal may read or write. `always` lists the fields it
+     * may use on every row it can reach (`"all"`: every field that is not
+     * governed); `perRow` maps a field it may use only on some rows to the
+     * condition those rows meet. A field in neither is refused (`A4002`)
+     * wherever the request names it.
+     */
+    fieldsOf(question: PolicyQuestion & {
+        readonly access: "read" | "write";
+    }): PolicyAnswer<{
+        readonly always: "all" | readonly string[];
+        readonly perRow: {
+            readonly [field: string]: AvPolicyWhere | undefined;
+        };
+    }>;
+}
+export {};

package/dist/policy/policy-engine.js

@@ -0,0 +1 @@
+export {};

package/dist/policy/policy-nested-write.runtime.d.ts

@@ -0,0 +1,38 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvContractCore } from "../contracts/contract.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type PolicyCondition } from "./policy-condition.js";
+import { type PolicySession } from "./policy-session.js";
+type Row = Readonly<Record<string, unknown>>;
+/** The rows a level's records write: new rows, or rows a condition reaches before the write. */
+export type NestedParent = {
+    readonly kind: "new";
+} | {
+    readonly kind: "existing";
+    readonly reach: PolicyCondition;
+};
+/** The checks after the write: told the root rows it wrote, the refusal or `undefined`. */
+export type NestedWriteCheck = (rows: readonly Row[]) => Promise<AvOperationFailureResponse | undefined>;
+/**
+ * What a nested write needs: a refusal before it runs, or the root record the
+ * adapter runs (its to-many `$update` and `$delete` narrowed to the rows within
+ * their scopes) and the check after it.
+ */
+export type NestedWritePlan = {
+    readonly kind: "refused";
+    readonly response: AvOperationFailureResponse;
+} | {
+    readonly kind: "planned";
+    readonly record: Row;
+    readonly after: NestedWriteCheck;
+};
+/** Whether `record` of `resource` writes a relation through a directive. */
+export declare function writesNested(core: AvContractCore, resource: string, record: unknown): boolean;
+/**
+ * The policy of the nested writes in one root record (see the module comment):
+ * the refusal before the call, or the checks after it. `created` says the root
+ * rows are created by this write, so they too are read as stored and asked
+ * `can({ action: "create", row })` after the call.
+ */
+export declare function planNestedWrites(session: PolicySession, core: AvContractCore, model: AvAdapterModel, resource: string, record: Row, parent: NestedParent): Promise<NestedWritePlan>;
+export {};

package/dist/policy/policy-nested-write.runtime.js

@@ -0,0 +1,449 @@
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { isRelationMutationDirective } from "../runtime/mutation-planner.js";
+import { frozenCopy } from "../runtime/readonly-value.js";
+import { policyRefusal } from "./policy-admission.js";
+import { afterUpdate, checkChanged, rowFieldsOf, } from "./policy-after-update.runtime.js";
+import { allOf, noneOf, someOf, whereOf, } from "./policy-condition.js";
+import { identifiedRows, identifierOf } from "./policy-read.runtime.js";
+import { fieldAccess } from "./policy-session.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isPlainObject(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const DROPPED = Symbol("dropped");
+function rewritten(value, replaced) {
+    if (value !== null && typeof value === "object" && replaced.has(value)) {
+        return replaced.get(value);
+    }
+    if (Array.isArray(value)) {
+        const entries = value.map((entry) => rewritten(entry, replaced));
+        return entries.every((entry, index) => entry === value[index])
+            ? value
+            : entries.filter((entry) => entry !== DROPPED);
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    let changed = false;
+    const copy = {};
+    for (const [key, member] of Object.entries(value)) {
+        const next = rewritten(member, replaced);
+        changed ||= next !== member;
+        copy[key] = next === DROPPED ? [] : next;
+    }
+    return changed ? copy : value;
+}
+function conditionOf(where) {
+    return isRecord(where) && Object.keys(where).length > 0 ? where : true;
+}
+function relationOf(core, resource, name) {
+    const field = lookupField(lookupResource(core, resource), name);
+    return field?.kind === "relation"
+        ? field
+        : undefined;
+}
+export function writesNested(core, resource, record) {
+    return (isRecord(record) &&
+        Object.entries(record).some(([key, value]) => isRecord(value) &&
+            relationOf(core, resource, key) !== undefined &&
+            Object.keys(value).some(isRelationMutationDirective)));
+}
+class NestedRefusal extends Error {
+    name = "NestedRefusal";
+}
+const QUESTION_MESSAGES = {
+    link: (resource) => `The policy does not allow this nested write to link or unlink a row of Resource "${resource}" outside what the caller may change or read.`,
+    update: (resource) => `The policy does not allow this nested write to change a row of Resource "${resource}" outside what the caller may change.`,
+    delete: (resource) => `The policy does not allow this nested write to delete a row of Resource "${resource}" outside what the caller may delete.`,
+    fields: (resource) => `The policy does not allow this nested write to write a field of Resource "${resource}" on every row it reaches.`,
+};
+function linkedTo(inverse, parents) {
+    if (parents === false) {
+        return false;
+    }
+    const reach = whereOf(parents);
+    return inverse.cardinality === "one"
+        ? { [inverse.name]: reach }
+        : { [inverse.name]: { some: reach } };
+}
+class NestedWalk {
+    session;
+    core;
+    model;
+    questions = new Map();
+    replaced = new Map();
+    constructor(session, core, model) {
+        this.session = session;
+        this.core = core;
+        this.model = model;
+    }
+    ask(resource, kind, condition) {
+        if (condition === false) {
+            return;
+        }
+        const key = `${resource}\u0000${kind}`;
+        let question = this.questions.get(key);
+        if (question === undefined) {
+            question = { resource, kind, conditions: [] };
+            this.questions.set(key, question);
+        }
+        question.conditions.push(condition);
+    }
+    async answer() {
+        for (const { resource, kind, conditions } of this.questions.values()) {
+            const reach = someOf(conditions);
+            if (reach !== false &&
+                (await this.session.exists(resource, whereOf(reach)))) {
+                return policyRefusal(QUESTION_MESSAGES[kind](resource));
+            }
+        }
+        return undefined;
+    }
+    identifier(resource) {
+        const identifier = identifierOf(this.model, resource);
+        if (identifier.length === 0) {
+            throw new NestedRefusal(`The policy checks the rows a nested write reaches in Resource "${resource}" by identifier, and the Resource has none.`);
+        }
+        return identifier;
+    }
+    async grantsOf(resource, records) {
+        const fields = await this.session.fields(resource, "write");
+        const grants = new Map();
+        for (const record of records) {
+            for (const [name, value] of Object.entries(record)) {
+                if (value === undefined) {
+                    continue;
+                }
+                const relation = relationOf(this.core, resource, name);
+                for (const member of [name, ...(relation?.referenceFields ?? [])]) {
+                    const access = fieldAccess(this.core, resource, fields, member);
+                    if (access === "never") {
+                        throw new NestedRefusal(`The policy does not allow writing field "${member}" of Resource "${resource}".`);
+                    }
+                    if (access !== "always") {
+                        grants.set(member, access);
+                    }
+                }
+            }
+        }
+        return [...grants.values()];
+    }
+    async level(resource, parent, records) {
+        const relations = new Map();
+        for (const record of records) {
+            for (const [key, value] of Object.entries(record)) {
+                if (!isRecord(value) ||
+                    relationOf(this.core, resource, key) === undefined) {
+                    continue;
+                }
+                for (const [directive, operand] of Object.entries(value)) {
+                    if (isRelationMutationDirective(directive) && operand !== undefined) {
+                        let operands = relations.get(key);
+                        if (operands === undefined) {
+                            operands = [];
+                            relations.set(key, operands);
+                        }
+                        operands.push([directive, operand]);
+                    }
+                }
+            }
+        }
+        const checks = [];
+        for (const [name, operands] of relations) {
+            checks.push(...(await this.relation(resource, parent, name, operands)));
+        }
+        return checks;
+    }
+    async relation(resource, parent, name, operands) {
+        const core = this.core;
+        const relation = relationOf(core, resource, name);
+        const target = relation.target;
+        const back = relation.inverse === undefined
+            ? undefined
+            : relationOf(core, target, relation.inverse);
+        const inverse = back === undefined || relation.inverse === undefined
+            ? undefined
+            : { name: relation.inverse, cardinality: back.cardinality };
+        const throughInverse = () => {
+            if (inverse === undefined) {
+                throw new NestedRefusal(`The policy checks the rows relation "${name}" of Resource "${resource}" reaches through its other end, and the relation states none.`);
+            }
+            return inverse;
+        };
+        let reached;
+        const linked = () => {
+            reached ??=
+                parent.kind === "new"
+                    ? false
+                    : linkedTo(throughInverse(), parent.reach);
+            return reached;
+        };
+        const read = await this.session.scope(target, "read");
+        const change = allOf(await this.session.scope(target, "update"), read);
+        const remove = allOf(await this.session.scope(target, "delete"), read);
+        const targetHolds = relation.referenceFields === undefined;
+        const linkScope = targetHolds ? change : read;
+        const many = relation.cardinality === "many";
+        const selectors = [];
+        const created = [];
+        const checks = [];
+        const changing = [];
+        const link = (selector) => {
+            if (isRecord(selector)) {
+                selectors.push(selector);
+                this.ask(target, "link", allOf(selector, noneOf(linkScope)));
+                if (targetHolds) {
+                    changing.push(selector);
+                }
+            }
+        };
+        const unlinkLinked = (except) => {
+            const unlinked = allOf(linked(), noneOf(except));
+            this.ask(target, "link", allOf(unlinked, noneOf(linkScope)));
+            if (targetHolds) {
+                changing.push(unlinked);
+            }
+        };
+        const entriesOf = (operand) => many && Array.isArray(operand) ? operand : [operand];
+        for (const [directive, operand] of operands) {
+            if (!many &&
+                targetHolds &&
+                parent.kind === "existing" &&
+                (directive === "$create" ||
+                    directive === "$connect" ||
+                    directive === "$connectOrCreate" ||
+                    directive === "$set")) {
+                unlinkLinked(false);
+            }
+            switch (directive) {
+                case "$create":
+                    created.push(...entriesOf(operand).filter(isRecord));
+                    break;
+                case "$connect":
+                    entriesOf(operand).forEach(link);
+                    break;
+                case "$connectOrCreate":
+                    for (const entry of entriesOf(operand)) {
+                        if (isRecord(entry)) {
+                            link(entry.where);
+                            if (isRecord(entry.create)) {
+                                created.push(entry.create);
+                            }
+                        }
+                    }
+                    break;
+                case "$disconnect":
+                    if (many) {
+                        entriesOf(operand).forEach(link);
+                    }
+                    else {
+                        unlinkLinked(false);
+                    }
+                    break;
+                case "$set":
+                    if (!many) {
+                        if (operand === null) {
+                            unlinkLinked(false);
+                        }
+                        else {
+                            link(operand);
+                        }
+                        break;
+                    }
+                    {
+                        const kept = (Array.isArray(operand) ? operand : []).filter(isRecord);
+                        kept.forEach(link);
+                        unlinkLinked(someOf(kept));
+                    }
+                    break;
+                case "$update":
+                    for (const entry of entriesOf(operand)) {
+                        if (isRecord(entry) && isRecord(entry.data)) {
+                            checks.push(await this.changed(target, allOf(linked(), conditionOf(entry.where)), change, entry.data, many ? entry : undefined));
+                        }
+                    }
+                    break;
+                case "$upsert":
+                    for (const entry of entriesOf(operand)) {
+                        if (!isRecord(entry)) {
+                            continue;
+                        }
+                        const reach = allOf(linked(), conditionOf(entry.where));
+                        if (reach !== false &&
+                            isRecord(entry.update) &&
+                            (await this.session.exists(target, whereOf(reach)))) {
+                            checks.push(await this.changed(target, reach, change, entry.update));
+                        }
+                        else if (isRecord(entry.create)) {
+                            created.push(entry.create);
+                        }
+                    }
+                    break;
+                case "$delete":
+                    for (const entry of entriesOf(operand)) {
+                        const reach = allOf(linked(), conditionOf(isRecord(entry) ? entry.where : undefined));
+                        if (many && isRecord(entry)) {
+                            await this.narrow(entry, target, reach, remove);
+                        }
+                        else {
+                            this.ask(target, "delete", allOf(reach, noneOf(remove)));
+                        }
+                    }
+                    break;
+            }
+        }
+        if (changing.length > 0) {
+            checks.push(await this.relinked(target, inverse, read, changing));
+        }
+        if (created.length > 0) {
+            checks.push(await this.creates(resource, target, throughInverse(), linked(), selectors, created));
+        }
+        return checks;
+    }
+    async narrow(entry, resource, reach, scope) {
+        const identifier = this.identifier(resource);
+        const within = allOf(reach, scope);
+        const rows = within === false
+            ? []
+            : await this.session.rows(resource, whereOf(within), identifier);
+        const where = identifiedRows(this.core, identifier, resource, rows);
+        this.replaced.set(entry, where === false ? DROPPED : { ...entry, where: whereOf(where) });
+        return rows;
+    }
+    async changed(resource, reach, scope, data, entry) {
+        const identifier = this.identifier(resource);
+        let rows;
+        if (entry === undefined) {
+            this.ask(resource, "update", allOf(reach, noneOf(scope)));
+            rows =
+                reach === false
+                    ? []
+                    : await this.session.rows(resource, whereOf(reach), identifier);
+        }
+        else {
+            rows = await this.narrow(entry, resource, reach, scope);
+            reach =
+                rows.length === 0
+                    ? false
+                    : identifiedRows(this.core, identifier, resource, rows);
+        }
+        const grants = await this.grantsOf(resource, [data]);
+        if (grants.length > 0) {
+            this.ask(resource, "fields", allOf(reach, someOf(grants.map(noneOf))));
+        }
+        const after = await afterUpdate(this.session, this.core, this.model, resource, data, true);
+        const inner = await this.level(resource, { kind: "existing", reach }, [
+            data,
+        ]);
+        return async () => {
+            if (after !== undefined) {
+                const refused = await checkChanged(this.session, this.core, this.model, resource, after, rows);
+                if (refused !== undefined) {
+                    return refused;
+                }
+            }
+            return runChecks(inner, rows);
+        };
+    }
+    async relinked(resource, inverse, read, changing) {
+        const identifier = this.identifier(resource);
+        const reach = someOf(changing);
+        const rows = reach === false
+            ? []
+            : await this.session.rows(resource, whereOf(reach), identifier);
+        const after = (inverse === undefined
+            ? undefined
+            : await afterUpdate(this.session, this.core, this.model, resource, { [inverse.name]: {} }, true)) ?? { moveOut: read === true ? undefined : read, after: true };
+        return () => checkChanged(this.session, this.core, this.model, resource, after, rows);
+    }
+    async creates(parentResource, resource, inverse, linked, selectors, records) {
+        const identifier = this.identifier(resource);
+        const parentIdentifier = this.identifier(parentResource);
+        const there = someOf([linked, ...selectors]);
+        const before = there === false
+            ? []
+            : await this.session.rows(resource, whereOf(there), identifier);
+        const grants = await this.grantsOf(resource, records);
+        const inner = await this.level(resource, { kind: "new" }, records);
+        return async (parents) => {
+            if (parents.length === 0) {
+                return undefined;
+            }
+            const fresh = this.session.renewed();
+            const reach = allOf(linkedTo(inverse, identifiedRows(this.core, parentIdentifier, parentResource, parents)), before.length === 0
+                ? true
+                : noneOf(identifiedRows(this.core, identifier, resource, before)));
+            const rows = reach === false
+                ? []
+                : await fresh.rows(resource, whereOf(reach), [
+                    ...new Set([...identifier, ...rowFieldsOf(this.core, resource)]),
+                ]);
+            const refused = await checkCreatedRows(fresh, this.core, identifier, resource, grants, rows);
+            return refused ?? runChecks(inner, rows);
+        };
+    }
+}
+async function runChecks(checks, rows) {
+    for (const check of checks) {
+        const refused = await check(rows);
+        if (refused !== undefined) {
+            return refused;
+        }
+    }
+    return undefined;
+}
+async function checkCreatedRows(session, core, identifier, resource, grants, rows) {
+    if (rows.length === 0) {
+        return undefined;
+    }
+    const answers = await Promise.all(rows.map((row) => session.can(resource, "create", frozenCopy(row))));
+    if (answers.includes(false)) {
+        return policyRefusal(`The policy does not allow creating this row of Resource "${resource}".`);
+    }
+    const missed = allOf(identifiedRows(core, identifier, resource, rows), someOf(grants.map(noneOf)));
+    if (missed !== false && (await session.exists(resource, whereOf(missed)))) {
+        return policyRefusal(`The policy does not allow writing a field of Resource "${resource}" on the row this request creates.`);
+    }
+    return undefined;
+}
+export async function planNestedWrites(session, core, model, resource, record, parent) {
+    const walk = new NestedWalk(session, core, model);
+    try {
+        const identifier = identifierOf(model, resource);
+        if (identifier.length === 0) {
+            throw new NestedRefusal(`The policy checks the rows a nested write reaches by identifier, and Resource "${resource}" has none.`);
+        }
+        const checks = await walk.level(resource, parent, [record]);
+        const refused = await walk.answer();
+        if (refused !== undefined) {
+            return { kind: "refused", response: refused };
+        }
+        return {
+            kind: "planned",
+            record: rewritten(record, walk.replaced),
+            after: async (rows) => {
+                if (parent.kind === "new" && rows.length > 0) {
+                    const fresh = session.renewed();
+                    const stored = await fresh.rows(resource, whereOf(identifiedRows(core, identifier, resource, rows)), [...new Set([...identifier, ...rowFieldsOf(core, resource)])]);
+                    const refusal = await checkCreatedRows(fresh, core, identifier, resource, [], stored);
+                    if (refusal !== undefined) {
+                        return refusal;
+                    }
+                }
+                return runChecks(checks, rows);
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof NestedRefusal) {
+            return { kind: "refused", response: policyRefusal(error.message) };
+        }
+        throw error;
+    }
+}