@aventara/core 1.0.0-rc.1 → 1.0.0-rc.10

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

@@ -0,0 +1,545 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
+import { toOneRelinkWithRewrite } from "../contracts/capability.js";
+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, beforeFields, checkChanged, coveredBefore, rowFieldsOf, unchangedSince, } from "./policy-after-update.runtime.js";
+import { allOf, noneOf, someOf, whereOf, } from "./policy-condition.js";
+import { NamedRows } from "./policy-named-rows.js";
+import { identifiedRows } from "./policy-read.runtime.js";
+import { isHeldTarget } from "./policy-reference-write.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;
+}
+function namesReference(selector, references) {
+    if (references === undefined) {
+        return false;
+    }
+    return (Object.keys(selector).length === references.length &&
+        references.every((reference) => {
+            const value = Object.hasOwn(selector, reference)
+                ? selector[reference]
+                : undefined;
+            return (value !== undefined &&
+                value !== null &&
+                !Array.isArray(value) &&
+                !isPlainObject(value));
+        }));
+}
+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();
+    named = new Map();
+    replaced = new Map();
+    held = [];
+    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);
+    }
+    name(resource, selector, scope) {
+        let rows = this.named.get(resource);
+        if (rows === undefined) {
+            rows = new NamedRows();
+            this.named.set(resource, rows);
+        }
+        rows.add(selector, scope);
+    }
+    async answer() {
+        for (const [resource, rows] of this.named) {
+            if (rows.size > 0 && !(await rows.within(this.session, resource))) {
+                return policyRefusal(QUESTION_MESSAGES.link(resource));
+            }
+        }
+        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 = adapterPrimaryIdentifier(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, action) {
+        const fields = await this.session.fields(resource, {
+            access: "write",
+            action,
+        });
+        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)) {
+                const relation = isRecord(value)
+                    ? relationOf(this.core, resource, key)
+                    : undefined;
+                if (!isRecord(value) || relation === undefined) {
+                    continue;
+                }
+                const paired = relation.cardinality === "one"
+                    ? toOneRelinkWithRewrite(Object.fromEntries(Object.entries(value).filter(([, operand]) => operand !== undefined)))
+                    : undefined;
+                if (paired !== undefined) {
+                    throw new NestedRefusal(`Relation "${key}" of Resource "${resource}" pairs ${paired.rewrite.join("/")} with ${paired.relink.join("/")}: the row it would update is the newly linked one, which the policy cannot check before the write.`);
+                }
+                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 unheld = !targetHolds && !isHeldTarget(core, this.session.unheld, target);
+        const linkScope = targetHolds ? change : unheld ? true : read;
+        const selectorScope = (selector) => unheld && !namesReference(selector, relation.references)
+            ? read
+            : linkScope;
+        const many = relation.cardinality === "many";
+        const selectors = [];
+        const created = [];
+        const checks = [];
+        const changing = [];
+        const link = (selector, named = true) => {
+            if (isRecord(selector)) {
+                selectors.push(selector);
+                const scope = selectorScope(selector);
+                if (named) {
+                    this.name(target, selector, scope);
+                }
+                else {
+                    this.ask(target, "link", allOf(selector, noneOf(scope)));
+                }
+                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((one) => {
+                        link(one);
+                    });
+                    break;
+                case "$connectOrCreate":
+                    for (const entry of entriesOf(operand)) {
+                        if (isRecord(entry)) {
+                            link(entry.where, false);
+                            if (isRecord(entry.create)) {
+                                created.push(entry.create);
+                            }
+                        }
+                    }
+                    break;
+                case "$disconnect":
+                    if (many) {
+                        entriesOf(operand).forEach((one) => {
+                            link(one);
+                        });
+                    }
+                    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((one) => {
+                            link(one);
+                        });
+                        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 ? { kind: "narrow", entry } : { kind: "hold", entry }));
+                        }
+                    }
+                    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, fields = this.identifier(resource), held = false) {
+        const identifier = this.identifier(resource);
+        const within = allOf(reach, scope);
+        const rows = within === false
+            ? []
+            : await this.session.rows(resource, whereOf(within), fields);
+        const where = held
+            ? unchangedSince(this.core, this.model, resource, rows)
+            : identifiedRows(this.core, identifier, resource, rows);
+        this.replaced.set(entry, where === false ? DROPPED : { ...entry, where: whereOf(where) });
+        return rows;
+    }
+    hold(entry, resource, rows) {
+        const unchanged = unchangedSince(this.core, this.model, resource, rows);
+        const where = typeof unchanged === "boolean"
+            ? false
+            : allOf(conditionOf(entry.where), unchanged);
+        if (where === false) {
+            return;
+        }
+        this.replaced.set(entry, { ...entry, where: whereOf(where) });
+        this.held.push({ resource, rows });
+    }
+    async failed() {
+        const fresh = this.session.renewed();
+        for (const { resource, rows } of this.held) {
+            const changed = allOf(identifiedRows(this.core, this.identifier(resource), resource, rows), noneOf(unchangedSince(this.core, this.model, resource, rows)));
+            if (changed !== false &&
+                (await fresh.exists(resource, whereOf(changed)))) {
+                return policyRefusal(`The policy checks this nested update of Resource "${resource}" against the row as it was before it, and a concurrent write changed that row before it ran, so it was not applied.`);
+            }
+        }
+        return undefined;
+    }
+    async changed(resource, reach, scope, data, directive) {
+        const identifier = this.identifier(resource);
+        const after = await afterUpdate(this.session, this.core, this.model, resource, data, true);
+        const fields = beforeFields(this.core, this.model, resource, after);
+        let rows;
+        if (directive?.kind !== "narrow") {
+            this.ask(resource, "update", allOf(reach, noneOf(scope)));
+            rows =
+                reach === false
+                    ? []
+                    : await this.session.rows(resource, whereOf(reach), fields);
+            if (directive !== undefined && after?.before === true) {
+                this.hold(directive.entry, resource, rows);
+            }
+        }
+        else {
+            rows = await this.narrow(directive.entry, resource, reach, scope, fields, after?.before === true);
+            reach =
+                rows.length === 0
+                    ? false
+                    : identifiedRows(this.core, identifier, resource, rows);
+        }
+        const grants = await this.grantsOf(resource, [data], "update");
+        if (grants.length > 0) {
+            this.ask(resource, "fields", allOf(reach, someOf(grants.map(noneOf))));
+        }
+        const before = await coveredBefore(this.session, this.core, this.model, resource, after, rows);
+        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, false, before);
+                if (refused !== undefined) {
+                    return refused;
+                }
+            }
+            return runChecks(inner, rows);
+        };
+    }
+    async relinked(resource, inverse, read, changing) {
+        this.identifier(resource);
+        const reach = someOf(changing);
+        const after = (inverse === undefined
+            ? undefined
+            : await afterUpdate(this.session, this.core, this.model, resource, { [inverse.name]: {} }, true)) ?? {
+            moveOut: read === true ? undefined : read,
+            after: true,
+            before: this.session.checksAfter(resource, "update"),
+        };
+        const rows = reach === false
+            ? []
+            : await this.session.rows(resource, whereOf(reach), beforeFields(this.core, this.model, resource, after));
+        const before = await coveredBefore(this.session, this.core, this.model, resource, after, rows);
+        return () => checkChanged(this.session, this.core, this.model, resource, after, rows, false, before);
+    }
+    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, "create");
+        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 = adapterPrimaryIdentifier(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),
+            failed: () => walk.failed(),
+            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;
+    }
+}

package/dist/policy/policy-read.runtime.d.ts

@@ -0,0 +1,81 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvContractCore } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { PlannedReadOperation, ReadProjectionPlan } from "../runtime/computed-read-runtime.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type PolicyCondition } from "./policy-condition.js";
+import { type PolicySession } from "./policy-session.js";
+/** The answer once the policy checked it: its rows, or the refusal. */
+export type PolicySettlement = {
+    readonly ok: true;
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly response: AvOperationFailureResponse;
+};
+/** What one read runs once its policy is applied. */
+export type PolicyRead = {
+    /** The policy refuses the read before it runs. */
+    readonly kind: "refused";
+    readonly response: AvOperationFailureResponse;
+} | {
+    /** The read reaches no row: its answer, without the adapter. */
+    readonly kind: "empty";
+    readonly data: unknown;
+} | {
+    readonly kind: "run";
+    /** The operation the adapter runs: the request's own, or a unique read's first-style form. */
+    readonly identity: AvOperationIdentity;
+    readonly arguments: unknown;
+    readonly plan: PlannedReadOperation;
+    /**
+     * What the returned rows are checked for after the adapter answers (an
+     * `exists` per level): the root level's conditions, each a row it must
+     * not meet, and whether a level below the root is checked.
+     */
+    readonly checks: {
+        readonly root: readonly PolicyCondition[];
+        readonly nested: boolean;
+    };
+    /** The returned rows checked, and every emptied relation filled. */
+    readonly settle: (data: unknown) => Promise<PolicySettlement>;
+};
+/**
+ * How a write's root rows are reached (`policy-write.runtime.ts`): the
+ * condition ANDed into its `where`, or `undefined` for a write whose `where`
+ * stays as sent (a create has none, an upsert's is checked before it runs);
+ * and whether each returned row carries its identifier, for the checks that
+ * follow the write.
+ */
+type PolicyRootRows = {
+    readonly scope: PolicyCondition | undefined;
+    readonly identified: boolean;
+    /**
+     * The fields each returned root row carries besides the caller's projection (its
+     * identifier among them when `identified`): what the after check asks `can` about,
+     * read from the write's own answer rather than read again. Trimmed before the
+     * caller sees it.
+     */
+    readonly carried?: readonly string[];
+};
+type Row = Readonly<Record<string, unknown>>;
+/**
+ * One read's policy (see the module comment): what the adapter runs, and the
+ * checks its answer goes through; or the empty answer when the read reaches no
+ * row. A write's answer is read the same way, its root reached as `rows`
+ * says (`policy-write.runtime.ts`); a read's root is reached by its read scope.
+ */
+export declare function enforceReadPolicy(session: PolicySession, core: AvContractCore, model: AvAdapterModel, request: AvOperationIdentity & {
+    readonly resource: string;
+}, plan: PlannedReadOperation, adapterArguments: unknown, rows?: PolicyRootRows): Promise<PolicyRead>;
+/**
+ * What the rows an answer returns are checked for after the adapter answers, by
+ * the projection level that returns them: each level's conditions, each a row
+ * it must not meet (a to-one level's rows outside their read scope, a level's
+ * rows outside the grant of a field it returns that is readable on some rows
+ * only). Empty when nothing is checked after the answer.
+ */
+export declare function returnedRowChecks(session: PolicySession, core: AvContractCore, plan: PlannedReadOperation): Promise<Map<ReadProjectionPlan, readonly PolicyCondition[]>>;
+/** A condition naming exactly `rows` of `resource` by their identifier. */
+export declare function identifiedRows(core: AvContractCore, identifier: readonly string[], resource: string, rows: readonly Row[]): PolicyCondition;
+export {};