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

package/dist/policy/policy-admission.js

@@ -0,0 +1,409 @@
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { defaultProjectionFields } from "../runtime/computed-read-runtime.js";
+import { valueAt, writeRecordPathsOf } from "../runtime/field-stage.runtime.js";
+import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "../runtime/mutation-planner.js";
+import { operationFailure } from "../runtime/operation-response.js";
+import { everyOf, noneOf, someOf, } from "./policy-condition.js";
+import { fieldAccess, } from "./policy-session.js";
+export function policyRefusal(message) {
+    return operationFailure("A4002", { message });
+}
+export function policyActionsOf(family) {
+    switch (family) {
+        case "find":
+            return ["read"];
+        case "create":
+            return ["create"];
+        case "update":
+            return ["update"];
+        case "delete":
+            return ["delete"];
+        case "upsert":
+            return ["create", "update"];
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+class FieldWalk {
+    active;
+    used = new Map();
+    nodes = [];
+    constructor(active) {
+        this.active = active;
+    }
+    use(resource, field) {
+        let fields = this.used.get(resource);
+        if (fields === undefined) {
+            fields = new Set();
+            this.used.set(resource, fields);
+        }
+        fields.add(field);
+    }
+    node(resource, where) {
+        const node = { resource, where, fields: new Set() };
+        this.nodes.push(node);
+        return node;
+    }
+    relation(resource, name) {
+        const field = lookupField(lookupResource(this.active, resource), name);
+        return field?.kind === "relation"
+            ? field
+            : undefined;
+    }
+    defaults(resource) {
+        for (const field of defaultProjectionFields(this.active, resource)) {
+            this.use(resource, field);
+        }
+    }
+    projection(resource, args) {
+        if (Array.isArray(args.select)) {
+            for (const entry of args.select) {
+                if (entry === "$count") {
+                    continue;
+                }
+                if (entry === "$defaults") {
+                    this.defaults(resource);
+                    continue;
+                }
+                this.projectionEntry(resource, entry);
+            }
+            return;
+        }
+        this.defaults(resource);
+        if (Array.isArray(args.include)) {
+            for (const entry of args.include) {
+                this.projectionEntry(resource, entry);
+            }
+        }
+    }
+    projectionEntry(resource, entry) {
+        if (typeof entry === "string") {
+            this.use(resource, entry);
+            const relation = this.relation(resource, entry);
+            if (relation !== undefined) {
+                this.defaults(relation.target);
+            }
+            return;
+        }
+        if (!isRecord(entry)) {
+            return;
+        }
+        for (const [name, value] of Object.entries(entry)) {
+            this.use(resource, name);
+            const relation = this.relation(resource, name);
+            if (relation !== undefined) {
+                this.level(relation.target, isRecord(value) ? value : {});
+            }
+        }
+    }
+    level(resource, args) {
+        const node = this.node(resource, args.where);
+        this.where(resource, args.where, node);
+        this.orderBy(resource, args.orderBy, node);
+        if (isRecord(args.cursor)) {
+            for (const field of Object.keys(args.cursor)) {
+                this.use(resource, field);
+                node.fields.add(field);
+            }
+        }
+        this.projection(resource, args);
+    }
+    where(resource, where, node) {
+        if (!isRecord(where)) {
+            return;
+        }
+        for (const [key, value] of Object.entries(where)) {
+            if (key === "AND" || key === "OR" || key === "NOT") {
+                for (const entry of Array.isArray(value) ? value : [value]) {
+                    this.where(resource, entry, node);
+                }
+                continue;
+            }
+            this.use(resource, key);
+            node.fields.add(key);
+            const relation = this.relation(resource, key);
+            if (relation === undefined || !isRecord(value)) {
+                continue;
+            }
+            const inner = relation.cardinality === "many"
+                ? ["some", "every", "none"].flatMap((operator) => isRecord(value[operator]) ? [value[operator]] : [])
+                : [value];
+            for (const filter of inner) {
+                this.where(relation.target, filter, this.node(relation.target, filter));
+            }
+        }
+    }
+    orderBy(resource, orderBy, node) {
+        for (const entry of Array.isArray(orderBy) ? orderBy : [orderBy]) {
+            if (!isRecord(entry)) {
+                continue;
+            }
+            for (const [key, value] of Object.entries(entry)) {
+                this.use(resource, key);
+                node.fields.add(key);
+                const relation = this.relation(resource, key);
+                if (relation?.cardinality === "one" && isRecord(value)) {
+                    this.orderBy(relation.target, value, this.node(relation.target, undefined));
+                }
+            }
+        }
+    }
+}
+function projects(request) {
+    return request.family === "upsert" || request.variant !== "count";
+}
+function namedFields(active, request, args) {
+    const walk = new FieldWalk(active);
+    const level = isRecord(args) ? args : {};
+    const root = walk.node(request.resource, level.where);
+    walk.where(request.resource, level.where, root);
+    walk.orderBy(request.resource, level.orderBy, root);
+    if (isRecord(level.cursor)) {
+        for (const field of Object.keys(level.cursor)) {
+            walk.use(request.resource, field);
+            root.fields.add(field);
+        }
+    }
+    if (projects(request)) {
+        walk.projection(request.resource, level);
+    }
+    return walk;
+}
+function withoutConditional(core, resource, where, conditional) {
+    if (!isRecord(where)) {
+        return true;
+    }
+    const conditions = [];
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "AND") {
+            for (const entry of Array.isArray(value) ? value : [value]) {
+                conditions.push(withoutConditional(core, resource, entry, conditional));
+            }
+            continue;
+        }
+        if (key === "OR") {
+            conditions.push(Array.isArray(value)
+                ? someOf(value.map((entry) => withoutConditional(core, resource, entry, conditional)))
+                : true);
+            continue;
+        }
+        conditions.push(holdsConditional(core, resource, { [key]: value }, conditional)
+            ? true
+            : { [key]: value });
+    }
+    return everyOf(conditions);
+}
+function holdsConditional(core, resource, where, conditional) {
+    if (!isRecord(where)) {
+        return false;
+    }
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "AND" || key === "OR" || key === "NOT") {
+            if ((Array.isArray(value) ? value : [value]).some((entry) => holdsConditional(core, resource, entry, conditional))) {
+                return true;
+            }
+            continue;
+        }
+        if (conditional.get(resource)?.has(key) === true) {
+            return true;
+        }
+        const field = lookupField(lookupResource(core, resource), key);
+        if (field?.kind !== "relation" || !isRecord(value)) {
+            continue;
+        }
+        const inner = field.cardinality === "many"
+            ? [value.some, value.every, value.none]
+            : [value];
+        if (inner.some((filter) => holdsConditional(core, field.target, filter, conditional))) {
+            return true;
+        }
+    }
+    return false;
+}
+export async function admitByPolicy(session, core, active, request, args) {
+    for (const action of policyActionsOf(request.family)) {
+        if (!(await session.can(request.resource, action))) {
+            return policyRefusal(`The policy does not allow ${action} on Resource "${request.resource}".`);
+        }
+    }
+    const named = namedFields(active, request, args);
+    const resources = new Set([
+        ...named.used.keys(),
+        ...named.nodes.map((node) => node.resource),
+    ]);
+    const answers = new Map(await Promise.all([...resources].map(async (resource) => [
+        resource,
+        await session.fields(resource, { access: "read" }),
+    ])));
+    const conditional = new Map();
+    for (const [resource, fields] of named.used) {
+        const answer = answers.get(resource);
+        for (const field of fields) {
+            const access = fieldAccess(core, resource, answer, field);
+            if (access === "never") {
+                return policyRefusal(`The policy does not allow reading field "${field}" of Resource "${resource}".`);
+            }
+            if (access !== "always") {
+                let set = conditional.get(resource);
+                if (set === undefined) {
+                    set = new Set();
+                    conditional.set(resource, set);
+                }
+                set.add(field);
+            }
+        }
+    }
+    for (const node of named.nodes) {
+        const answer = answers.get(node.resource);
+        const grants = [];
+        const names = [];
+        for (const field of node.fields) {
+            const access = fieldAccess(core, node.resource, answer, field);
+            if (access !== "always" && access !== "never") {
+                grants.push(access);
+                names.push(field);
+            }
+        }
+        if (grants.length === 0) {
+            continue;
+        }
+        const reach = everyOf([
+            await session.scope(node.resource, "read"),
+            withoutConditional(core, node.resource, node.where, conditional),
+            someOf(grants.map(noneOf)),
+        ]);
+        if (reach === false) {
+            continue;
+        }
+        if (await session.exists(node.resource, reach === true ? {} : reach)) {
+            return policyRefusal(`The policy does not allow filtering, sorting or paging by ${names
+                .map((name) => `"${name}"`)
+                .join(", ")} of Resource "${node.resource}" on every row this request reaches.`);
+        }
+    }
+    return undefined;
+}
+function sentRecords(request, args) {
+    return writeRecordPathsOf(request.family, args).flatMap((path) => {
+        const record = valueAt(args, path);
+        return isRecord(record)
+            ? [
+                {
+                    record,
+                    stage: request.family === "create" || path[0] === "create"
+                        ? "create"
+                        : "update",
+                },
+            ]
+            : [];
+    });
+}
+async function admitNestedRecords(session, core, resource, directives) {
+    if (!isRecord(directives)) {
+        return undefined;
+    }
+    const owner = lookupResource(core, resource);
+    for (const [directive, operand] of Object.entries(directives)) {
+        if (!isRelationMutationDirective(directive)) {
+            continue;
+        }
+        for (const entry of Array.isArray(operand) ? operand : [operand]) {
+            for (const site of RELATION_MUTATION_RECORD_SITES[directive]) {
+                const record = site.key === undefined ? entry : valueAt(entry, [site.key]);
+                if (!isRecord(record)) {
+                    continue;
+                }
+                const fields = await session.fields(resource, {
+                    access: "write",
+                    action: site.stage,
+                });
+                for (const [field, value] of Object.entries(record)) {
+                    if (value === undefined) {
+                        continue;
+                    }
+                    const relation = lookupField(owner, field);
+                    const written = relation?.kind === "relation"
+                        ? [field, ...(relation.referenceFields ?? [])]
+                        : [field];
+                    for (const member of written) {
+                        if (fieldAccess(core, resource, fields, member) === "never") {
+                            return policyRefusal(`The policy does not allow writing field "${member}" of Resource "${resource}".`);
+                        }
+                    }
+                    if (relation?.kind === "relation") {
+                        const refused = await admitNestedRecords(session, core, relation.target, value);
+                        if (refused !== undefined) {
+                            return refused;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return undefined;
+}
+export async function admitWriteByPolicy(session, core, request, args) {
+    const records = sentRecords(request, args);
+    if (records.length === 0) {
+        return undefined;
+    }
+    const resource = request.resource;
+    const grants = [];
+    const names = [];
+    for (const { record, stage } of records) {
+        const fields = await session.fields(resource, {
+            access: "write",
+            action: stage,
+        });
+        for (const [field, value] of Object.entries(record)) {
+            if (value === undefined) {
+                continue;
+            }
+            const relation = lookupField(lookupResource(core, resource), field);
+            const written = relation?.kind === "relation"
+                ? [field, ...(relation.referenceFields ?? [])]
+                : [field];
+            if (relation?.kind === "relation") {
+                const refused = await admitNestedRecords(session, core, relation.target, value);
+                if (refused !== undefined) {
+                    return refused;
+                }
+            }
+            for (const member of written) {
+                const access = fieldAccess(core, resource, fields, member);
+                if (access === "never") {
+                    return policyRefusal(`The policy does not allow writing field "${member}" of Resource "${resource}".`);
+                }
+                if (access === "always") {
+                    continue;
+                }
+                if (stage === "create") {
+                    session.grantCreate(member, access);
+                    continue;
+                }
+                if (!names.includes(member)) {
+                    grants.push(access);
+                    names.push(member);
+                }
+            }
+        }
+    }
+    if (grants.length === 0) {
+        return undefined;
+    }
+    const level = isRecord(args) ? args : {};
+    const reach = everyOf([
+        await session.scope(resource, "update"),
+        await session.scope(resource, "read"),
+        isRecord(level.where) ? level.where : true,
+        someOf(grants.map(noneOf)),
+    ]);
+    if (reach !== false &&
+        (await session.exists(resource, reach === true ? {} : reach))) {
+        return policyRefusal(`The policy does not allow writing ${names
+            .map((name) => `"${name}"`)
+            .join(", ")} of Resource "${resource}" on every row this request reaches.`);
+    }
+    return undefined;
+}

package/dist/policy/policy-after-update.runtime.d.ts

@@ -0,0 +1,29 @@
+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 scalar fields of `resource` an after check reads the changed rows by. */
+export declare function rowFieldsOf(core: AvContractCore, resource: string): readonly string[];
+/** What the rows a write changed are checked for, after it. */
+export type AfterWrite = {
+    /** The read scope a moved-out row has left, when the data can move one. */
+    readonly moveOut: PolicyCondition | undefined;
+    /**
+     * Whether the after check runs: in a transaction, always; without one, the
+     * update is one `afterChecks` lists, and it is refused before it runs.
+     */
+    readonly after: boolean;
+};
+/** The checks after an update whose data is `data`; `undefined` when none applies. */
+export declare function afterUpdate(session: PolicySession, core: AvContractCore, model: AvAdapterModel, resource: string, data: unknown, inTransaction: boolean): Promise<AfterWrite | undefined>;
+/** The fields the after check asks `can` about: the identifier, then every scalar field. */
+export declare function afterCheckFields(core: AvContractCore, model: AvAdapterModel, resource: string): readonly string[];
+/**
+ * The changed rows held to the move-out and after checks: the refusal, or
+ * `undefined`. `returned` says that `changed` are the rows the write answered,
+ * carrying {@link afterCheckFields}.
+ */
+export declare function checkChanged(session: PolicySession, core: AvContractCore, model: AvAdapterModel, resource: string, checks: AfterWrite, changed: readonly Row[], returned?: boolean): Promise<AvOperationFailureResponse | undefined>;
+export {};

package/dist/policy/policy-after-update.runtime.js

@@ -0,0 +1,132 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { frozenCopy } from "../runtime/readonly-value.js";
+import { policyRefusal } from "./policy-admission.js";
+import { allOf, whereOf } from "./policy-condition.js";
+import { identifiedRows } from "./policy-read.runtime.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const fieldLists = new WeakMap();
+function listOf(core, key, make) {
+    let lists = fieldLists.get(core);
+    if (lists === undefined) {
+        lists = new Map();
+        fieldLists.set(core, lists);
+    }
+    let fields = lists.get(key);
+    if (fields === undefined) {
+        fields = make();
+        lists.set(key, fields);
+    }
+    return fields;
+}
+export function rowFieldsOf(core, resource) {
+    return listOf(core, `scalar\u0000${resource}`, () => Object.entries(lookupResource(core, resource)?.fields ?? {}).flatMap(([name, field]) => field?.kind === "scalar" && field.capabilities.select ? [name] : []));
+}
+function touches(core, model, resource, scope, data) {
+    const owner = lookupResource(core, resource);
+    const read = new Set();
+    const walk = (where) => {
+        if (!isRecord(where)) {
+            return;
+        }
+        for (const [key, value] of Object.entries(where)) {
+            if (key === "AND" || key === "OR" || key === "NOT") {
+                for (const entry of Array.isArray(value) ? value : [value]) {
+                    walk(entry);
+                }
+                continue;
+            }
+            read.add(key);
+            const field = lookupField(owner, key);
+            if (field?.kind !== "relation") {
+                continue;
+            }
+            if (field.cardinality === "one" && field.referenceFields !== undefined) {
+                for (const reference of field.referenceFields) {
+                    read.add(reference);
+                }
+            }
+            else {
+                for (const member of adapterPrimaryIdentifier(model, resource)) {
+                    read.add(member);
+                }
+            }
+        }
+    };
+    walk(scope);
+    return Object.entries(data).some(([name, value]) => {
+        if (value === undefined) {
+            return false;
+        }
+        const field = lookupField(owner, name);
+        const written = field?.kind === "relation"
+            ? [name, ...(field.referenceFields ?? [])]
+            : [name];
+        return written.some((member) => read.has(member));
+    });
+}
+export async function afterUpdate(session, core, model, resource, data, inTransaction) {
+    const read = await session.scope(resource, "read");
+    const moveOut = read !== true &&
+        isRecord(data) &&
+        touches(core, model, resource, read, data)
+        ? read
+        : undefined;
+    const after = inTransaction || session.checksAfter(resource, "update");
+    return moveOut === undefined && !after ? undefined : { moveOut, after };
+}
+function identityKey(identifier, row) {
+    return JSON.stringify(identifier.map((member) => row[member]), (_key, value) => (typeof value === "bigint" ? `#bigint(${value})` : value));
+}
+export function afterCheckFields(core, model, resource) {
+    return listOf(core, `after\u0000${resource}`, () => [
+        ...new Set([
+            ...adapterPrimaryIdentifier(model, resource),
+            ...rowFieldsOf(core, resource),
+        ]),
+    ]);
+}
+function rowOfFields(row, fields) {
+    const picked = {};
+    for (const field of fields) {
+        if (Object.hasOwn(row, field)) {
+            picked[field] = row[field];
+        }
+    }
+    return picked;
+}
+export async function checkChanged(session, core, model, resource, checks, changed, returned = false) {
+    if (changed.length === 0) {
+        return undefined;
+    }
+    const fresh = session.renewed();
+    const identifier = adapterPrimaryIdentifier(model, resource);
+    const these = identifiedRows(core, identifier, resource, changed);
+    if (these === false) {
+        return undefined;
+    }
+    const kept = checks.moveOut === undefined ? these : allOf(these, checks.moveOut);
+    const reread = checks.moveOut !== undefined || !returned;
+    const fields = afterCheckFields(core, model, resource);
+    const rows = kept === false || !reread
+        ? []
+        : await fresh.rows(resource, whereOf(kept), checks.after && !returned ? fields : [...identifier]);
+    if (checks.moveOut !== undefined) {
+        const found = new Set(rows.map((row) => identityKey(identifier, row)));
+        if (changed.some((row) => !found.has(identityKey(identifier, row)))) {
+            return policyRefusal(`The policy does not allow this change: it moves a row of Resource "${resource}" out of what the caller may read.`);
+        }
+    }
+    if (checks.after) {
+        const asked = returned
+            ? changed.map((row) => rowOfFields(row, fields))
+            : rows;
+        const answers = await Promise.all(asked.map((row) => fresh.can(resource, "update", frozenCopy(row))));
+        if (answers.includes(false)) {
+            return policyRefusal(`The policy does not allow this change: a changed row of Resource "${resource}" does not meet the condition its update grant sets.`);
+        }
+    }
+    return undefined;
+}

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

@@ -0,0 +1,15 @@
+import type { AvPolicyWhere } from "./policy-engine.js";
+/** A row condition: every row, no row, or a `where` fragment. */
+export type PolicyCondition = boolean | AvPolicyWhere;
+/** Both conditions: a constant folds, two fragments become one `AND`. */
+export declare function allOf(left: PolicyCondition, right: PolicyCondition): PolicyCondition;
+/** Either condition: a constant folds, two fragments become one `OR`. */
+export declare function anyOf(left: PolicyCondition, right: PolicyCondition): PolicyCondition;
+/** Every condition of `conditions`; `true` when there is none. */
+export declare function everyOf(conditions: readonly PolicyCondition[]): PolicyCondition;
+/** Any condition of `conditions`; `false` when there is none. */
+export declare function someOf(conditions: readonly PolicyCondition[]): PolicyCondition;
+/** The negation: a constant flips, a fragment is wrapped in `NOT`. */
+export declare function noneOf(condition: PolicyCondition): PolicyCondition;
+/** A condition as a `where` an `exists` or a read can run: `{}` for every row. */
+export declare function whereOf(condition: Exclude<PolicyCondition, false>): AvPolicyWhere;

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;
+}