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

package/dist/policy/policy-read.runtime.js

@@ -0,0 +1,503 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { policyRefusal } from "./policy-admission.js";
+import { allOf, anyOf, everyOf, noneOf, someOf, } from "./policy-condition.js";
+import { fieldAccess } from "./policy-session.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function relationOf(core, resource, name) {
+    const field = lookupField(lookupResource(core, resource), name);
+    return field?.kind === "relation"
+        ? field
+        : undefined;
+}
+function innerFilters(relation, value) {
+    return relation.cardinality === "many"
+        ? [value.some, value.every, value.none]
+        : [value];
+}
+class ReadTargets {
+    core;
+    resources = new Set();
+    constructor(core) {
+        this.core = core;
+    }
+    where(resource, 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]) {
+                    this.where(resource, entry);
+                }
+                continue;
+            }
+            const relation = relationOf(this.core, resource, key);
+            if (relation === undefined || !isRecord(value)) {
+                continue;
+            }
+            this.resources.add(relation.target);
+            for (const filter of innerFilters(relation, value)) {
+                this.where(relation.target, filter);
+            }
+        }
+    }
+    orderBy(resource, orderBy) {
+        for (const entry of Array.isArray(orderBy) ? orderBy : [orderBy]) {
+            if (!isRecord(entry)) {
+                continue;
+            }
+            for (const [key, value] of Object.entries(entry)) {
+                const relation = relationOf(this.core, resource, key);
+                if (relation !== undefined) {
+                    this.resources.add(relation.target);
+                    this.orderBy(relation.target, value);
+                }
+            }
+        }
+    }
+    select(resource, select) {
+        if (!Array.isArray(select)) {
+            return;
+        }
+        for (const entry of select) {
+            if (!isRecord(entry)) {
+                continue;
+            }
+            for (const [name, value] of Object.entries(entry)) {
+                const relation = relationOf(this.core, resource, name);
+                if (relation === undefined) {
+                    continue;
+                }
+                this.resources.add(relation.target);
+                if (isRecord(value)) {
+                    this.where(relation.target, value.where);
+                    this.orderBy(relation.target, value.orderBy);
+                    this.select(relation.target, value.select);
+                }
+            }
+        }
+    }
+}
+class ScopedWhere {
+    core;
+    scopes;
+    constructor(core, scopes) {
+        this.core = core;
+        this.scopes = scopes;
+    }
+    scope(resource) {
+        return this.scopes.get(resource) ?? true;
+    }
+    of(resource, where) {
+        if (!isRecord(where)) {
+            return where;
+        }
+        let changed = false;
+        const conditions = [];
+        const kept = {};
+        for (const [key, value] of Object.entries(where)) {
+            if ((key === "AND" || key === "OR") && Array.isArray(value)) {
+                const parts = value.map((entry) => this.of(resource, entry));
+                if (parts.every((part, index) => part === value[index])) {
+                    kept[key] = value;
+                    continue;
+                }
+                changed = true;
+                conditions.push(key === "AND"
+                    ? everyOf(parts)
+                    : someOf(parts));
+                continue;
+            }
+            if (key === "NOT") {
+                const part = this.of(resource, value);
+                if (part === value) {
+                    kept[key] = value;
+                    continue;
+                }
+                changed = true;
+                conditions.push(noneOf(part));
+                continue;
+            }
+            const relation = relationOf(this.core, resource, key);
+            const filter = relation === undefined || !isRecord(value)
+                ? undefined
+                : this.relationFilter(key, relation, value);
+            if (filter === undefined) {
+                kept[key] = value;
+                continue;
+            }
+            changed = true;
+            conditions.push(...filter);
+        }
+        if (!changed) {
+            return where;
+        }
+        return everyOf([
+            Object.keys(kept).length === 0 ? true : kept,
+            ...conditions,
+        ]);
+    }
+    relationFilter(key, relation, value) {
+        const scope = this.scope(relation.target);
+        if (relation.cardinality === "one") {
+            const inner = this.of(relation.target, value);
+            if (scope === true && inner === value) {
+                return undefined;
+            }
+            const condition = allOf(inner, scope);
+            return [
+                typeof condition === "boolean"
+                    ? condition && { [key]: {} }
+                    : { [key]: condition },
+            ];
+        }
+        const inner = Object.keys(value).map((operator) => [operator, this.of(relation.target, value[operator])]);
+        if (scope === true &&
+            inner.every(([operator, condition]) => condition === value[operator])) {
+            return undefined;
+        }
+        return inner.map(([operator, raw]) => {
+            const condition = raw;
+            if (operator === "every") {
+                const every = anyOf(condition, noneOf(scope));
+                return typeof every === "boolean"
+                    ? every || { [key]: { none: {} } }
+                    : { [key]: { every } };
+            }
+            const scoped = allOf(condition, scope);
+            if (typeof scoped !== "boolean") {
+                return { [key]: { [operator]: scoped } };
+            }
+            if (operator === "some") {
+                return scoped && { [key]: { some: {} } };
+            }
+            return !scoped || { [key]: { none: {} } };
+        });
+    }
+}
+function emptyRelationValue(select) {
+    const entries = Array.isArray(select) ? select : [];
+    if (!entries.includes("$count")) {
+        return [];
+    }
+    return entries.some((entry) => entry !== "$count")
+        ? { data: [], count: 0 }
+        : { count: 0 };
+}
+function scopedCursor(cursor, scope) {
+    if (!isRecord(cursor) || typeof scope === "boolean") {
+        return cursor;
+    }
+    return { ...cursor, AND: [scope] };
+}
+function withIdentifier(select, identifier) {
+    const missing = identifier.filter((member) => !select.includes(member));
+    return missing.length === 0 ? select : [...select, ...missing];
+}
+export async function enforceReadPolicy(session, core, model, request, plan, adapterArguments, rows) {
+    const args = isRecord(adapterArguments) ? adapterArguments : {};
+    const root = request.resource;
+    const targets = new ReadTargets(core);
+    targets.resources.add(root);
+    targets.where(root, args.where);
+    targets.orderBy(root, args.orderBy);
+    targets.select(root, args.select);
+    const scopes = new Map(await Promise.all([...targets.resources].map(async (resource) => [resource, await session.scope(resource, "read")])));
+    const scoped = new ScopedWhere(core, scopes);
+    let sortRefusal = unscopedSort(core, scoped, root, args.orderBy);
+    const checks = await returnedRowChecks(session, core, plan);
+    let identity = request;
+    let rootWhere = args.where;
+    let rootCursor = args.cursor;
+    const scope = rows === undefined ? scoped.scope(root) : rows.scope;
+    if (scope === undefined) {
+    }
+    else if (request.variant === "unique") {
+        if (scope !== true) {
+            const within = allOf(args.where, scope);
+            if (within === false) {
+                return { kind: "empty", data: null };
+            }
+            const first = firstVariantOf(core, root, request.family);
+            if (rows !== undefined &&
+                (request.family === "update" || request.family === "delete")) {
+                rootWhere = { ...args.where, AND: [scope] };
+            }
+            else if (first !== undefined) {
+                identity = first;
+                rootWhere = within;
+            }
+            else if (!(await session.exists(root, within))) {
+                return { kind: "empty", data: null };
+            }
+        }
+    }
+    else {
+        const where = everyOf([
+            args.where === undefined
+                ? true
+                : scoped.of(root, args.where),
+            scope,
+        ]);
+        if (where === false) {
+            return {
+                kind: "empty",
+                data: request.variant === "many"
+                    ? []
+                    : request.variant === "count"
+                        ? 0
+                        : null,
+            };
+        }
+        rootWhere = where === true ? undefined : where;
+        rootCursor = scopedCursor(args.cursor, scope);
+    }
+    const rewriteLevel = (resource, select, level) => {
+        const entries = [];
+        const emptied = [];
+        const nested = new Map();
+        for (const entry of Array.isArray(select) ? select : []) {
+            const [name] = isRecord(entry) ? Object.keys(entry) : [];
+            const relation = name === undefined ? undefined : relationOf(core, resource, name);
+            if (relation === undefined || name === undefined) {
+                entries.push(entry);
+                continue;
+            }
+            const value = isRecord(entry[name])
+                ? entry[name]
+                : {};
+            const nestedLevel = level?.relations.find((candidate) => candidate.field === name)?.projection;
+            let rewritten = { ...value };
+            sortRefusal ??= unscopedSort(core, scoped, relation.target, value.orderBy);
+            if (relation.cardinality === "many") {
+                const where = everyOf([
+                    value.where === undefined
+                        ? true
+                        : scoped.of(relation.target, value.where),
+                    scoped.scope(relation.target),
+                ]);
+                if (where === false) {
+                    emptied.push({
+                        field: name,
+                        value: emptyRelationValue(value.select),
+                    });
+                    continue;
+                }
+                if (where === true) {
+                    delete rewritten.where;
+                }
+                else {
+                    rewritten.where = where;
+                }
+                if (value.cursor !== undefined) {
+                    rewritten.cursor = scopedCursor(value.cursor, scoped.scope(relation.target));
+                }
+            }
+            const inner = rewriteLevel(relation.target, value.select, nestedLevel);
+            nested.set(name, inner);
+            rewritten = { ...rewritten, select: inner.select };
+            entries.push({ [name]: rewritten });
+        }
+        const checked = level !== undefined &&
+            (checks.has(level) ||
+                (level === plan.projection && rows?.identified === true));
+        const carried = level !== undefined && level === plan.projection
+            ? (rows?.carried ?? [])
+            : [];
+        return {
+            select: withIdentifier(checked
+                ? withIdentifier(entries, adapterPrimaryIdentifier(model, resource))
+                : entries, carried),
+            emptied,
+            nested,
+        };
+    };
+    const rewritten = rewriteLevel(root, args.select, plan.projection);
+    if (sortRefusal !== undefined) {
+        return { kind: "refused", response: policyRefusal(sortRefusal) };
+    }
+    const runArguments = { ...args };
+    if (rootWhere === undefined) {
+        delete runArguments.where;
+    }
+    else {
+        runArguments.where = rootWhere;
+    }
+    if (rootCursor !== undefined) {
+        runArguments.cursor = rootCursor;
+    }
+    if (Array.isArray(args.select)) {
+        runArguments.select = rewritten.select;
+    }
+    const changesShape = checks.size > 0 || hasEmptied(rewritten);
+    return {
+        kind: "run",
+        identity,
+        arguments: runArguments,
+        plan: changesShape ||
+            rows?.identified === true ||
+            (rows?.carried?.length ?? 0) > 0
+            ? { ...plan, materialize: true }
+            : plan,
+        checks: {
+            root: plan.projection === undefined
+                ? []
+                : (checks.get(plan.projection) ?? []),
+            nested: [...checks.keys()].some((level) => level !== plan.projection),
+        },
+        settle: async (data) => (await rowsReadable(request.family === "find" ? session : session.renewed(), core, model, plan.projection, checks, data))
+            ? { ok: true, data: filledEmptied(rewritten, data) }
+            : {
+                ok: false,
+                response: policyRefusal("The policy does not allow reading every row or field this request returns."),
+            },
+    };
+}
+export async function returnedRowChecks(session, core, plan) {
+    const checks = new Map();
+    const collect = async (level, reachedOne) => {
+        if (level === undefined) {
+            return;
+        }
+        const fields = await session.fields(level.resource, { access: "read" });
+        const conditions = [];
+        if (reachedOne) {
+            const scope = await session.scope(level.resource, "read");
+            if (scope !== true) {
+                conditions.push(noneOf(scope));
+            }
+        }
+        for (const field of level.requested) {
+            const access = fieldAccess(core, level.resource, fields, field);
+            if (access !== "always" && access !== "never") {
+                conditions.push(noneOf(access));
+            }
+        }
+        if (conditions.length > 0) {
+            checks.set(level, conditions);
+        }
+        for (const relation of level.relations) {
+            await collect(relation.projection, relation.cardinality === "one");
+        }
+    };
+    await collect(plan.projection, false);
+    return checks;
+}
+function firstVariantOf(core, resource, family) {
+    const operations = lookupResource(core, resource)?.operations;
+    return family !== "create" &&
+        family !== "upsert" &&
+        operations?.[family]?.first !== undefined
+        ? { family, variant: "first" }
+        : undefined;
+}
+function hasEmptied(level) {
+    return (level.emptied.length > 0 ||
+        [...level.nested.values()].some((nested) => hasEmptied(nested)));
+}
+function unscopedSort(core, scoped, resource, orderBy) {
+    for (const entry of Array.isArray(orderBy) ? orderBy : [orderBy]) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        for (const key of Object.keys(entry)) {
+            const relation = relationOf(core, resource, key);
+            if (relation !== undefined && scoped.scope(relation.target) !== true) {
+                return `The policy does not allow sorting by relation "${key}" of Resource "${resource}": it reaches rows of "${relation.target}" this request may not read.`;
+            }
+        }
+    }
+    return undefined;
+}
+function rowsByLevel(level, rows, into) {
+    if (level === undefined) {
+        return;
+    }
+    const own = into.get(level) ?? [];
+    for (const row of rows) {
+        if (isRecord(row)) {
+            own.push(row);
+        }
+    }
+    into.set(level, own);
+    for (const relation of level.relations) {
+        const nested = [];
+        for (const row of own) {
+            const value = row[relation.field];
+            if (Array.isArray(value)) {
+                nested.push(...value);
+            }
+            else if (isRecord(value) && Array.isArray(value.data)) {
+                nested.push(...value.data);
+            }
+            else if (relation.cardinality === "one" && isRecord(value)) {
+                nested.push(value);
+            }
+        }
+        rowsByLevel(relation.projection, nested, into);
+    }
+}
+export function identifiedRows(core, identifier, resource, rows) {
+    const [single] = identifier;
+    if (identifier.length === 1 && single !== undefined) {
+        const values = [...new Set(rows.map((row) => row[single]))];
+        const field = lookupField(lookupResource(core, resource), single);
+        if (field?.kind === "scalar" && field.capabilities.filter?.includes("in")) {
+            return { [single]: { in: values } };
+        }
+        return someOf(values.map((value) => ({ [single]: value })));
+    }
+    return someOf(rows.map((row) => Object.fromEntries(identifier.map((member) => [member, row[member]]))));
+}
+async function rowsReadable(session, core, model, projection, checks, data) {
+    if (checks.size === 0 || projection === undefined) {
+        return true;
+    }
+    const levels = new Map();
+    rowsByLevel(projection, Array.isArray(data) ? data : [data], levels);
+    const questions = [...checks].map(async ([level, misses]) => {
+        const rows = levels.get(level) ?? [];
+        if (rows.length === 0) {
+            return false;
+        }
+        const miss = someOf(misses);
+        if (miss === false) {
+            return false;
+        }
+        if (miss === true) {
+            return true;
+        }
+        const identifier = adapterPrimaryIdentifier(model, level.resource);
+        const reach = allOf(identifiedRows(core, identifier, level.resource, rows), miss);
+        return (reach !== false &&
+            session.exists(level.resource, reach === true ? {} : reach));
+    });
+    const answers = await Promise.all(questions);
+    return !answers.some((answer) => answer === true);
+}
+function filledEmptied(scopedLevel, data) {
+    if (!hasEmptied(scopedLevel)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map((row) => filledEmptied(scopedLevel, row));
+    }
+    if (!isRecord(data)) {
+        return data;
+    }
+    const row = { ...data };
+    for (const emptied of scopedLevel.emptied) {
+        row[emptied.field] = structuredClone(emptied.value);
+    }
+    for (const [field, nested] of scopedLevel.nested) {
+        const value = row[field];
+        row[field] =
+            isRecord(value) && Array.isArray(value.data)
+                ? { ...value, data: filledEmptied(nested, value.data) }
+                : filledEmptied(nested, value);
+    }
+    return row;
+}

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

@@ -0,0 +1,51 @@
+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 { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { PolicySession } from "./policy-session.js";
+/**
+ * Whether a reference written to `target` is held to its read scope: where the
+ * Core Contract shows `target` and the engine does not list it in `unheld`
+ * (see the header). The one test of it: the hold below, a relation directive's
+ * link where the writing row holds the reference
+ * (`policy-nested-write.runtime.ts`), and the list the engine is told
+ * (`heldTargetsOf`) all read it.
+ */
+export declare function isHeldTarget(core: AvContractCore, unheld: readonly string[], target: string): boolean;
+/**
+ * The Resources a written reference is held to the read scope of, frozen: what
+ * `AvPolicyEngine.hosted` is told once the Framework is built.
+ */
+export declare function heldTargetsOf(core: AvContractCore, unheld: readonly string[]): readonly string[];
+/** A write's top-level records and the stage each is written at. */
+type ReferenceSite = {
+    readonly stage: "create" | "update";
+    readonly records: readonly unknown[];
+};
+/**
+ * What the policy does to a write's references: refuse the write before it
+ * runs, or hand the adapter its records with the held ones written as links.
+ */
+export type HeldReferences = {
+    readonly kind: "refused";
+    readonly response: AvOperationFailureResponse;
+} | {
+    readonly kind: "held";
+    /** Whether a record the write sends is written as links: the write may fail on one. */
+    readonly linked: boolean;
+    /** The value of a top-level argument (`data`, `create`, `update`) as the adapter runs it. */
+    readonly apply: (value: unknown, stage: "create" | "update") => unknown;
+};
+/**
+ * The references a write's records (`sites`, of the request's Resource, nested
+ * records included) write, held to their targets' read scopes: the refusal of
+ * a value that names no row, or that a record cannot hold inside the write and
+ * names a row outside the scope or not there (one count per target Resource);
+ * otherwise
+ * how the adapter's records write the held references as links. No query for a
+ * record written as links, nor where every target's scope is `true`.
+ */
+export declare function heldReferences(session: PolicySession, core: AvContractCore, model: AvAdapterModel, request: AvOperationIdentity & {
+    readonly resource: string;
+}, sites: readonly ReferenceSite[]): Promise<HeldReferences>;
+export {};