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

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

@@ -0,0 +1,494 @@
+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;
+}
+export function identifierOf(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : 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 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;
+    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;
+    }
+    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;
+                }
+            }
+            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, identifierOf(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 (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(session, 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, "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 = identifierOf(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-request.d.ts

@@ -0,0 +1,37 @@
+import type { AvAdapterOperationExecutor } from "../adapters/adapter-operation-executor.interface.js";
+import type { ResolvedPolicyConfig } from "../config/config.resolver.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvContract, AvContractCore } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { DiagnosticsReporter } from "../runtime/diagnostics-reporter.js";
+import { type CallerArgumentsView } from "../runtime/error-boundary.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { AvState } from "../runtime/request-state.js";
+import { type PolicySession } from "./policy-session.js";
+/** The principal an application call runs as (`{ as }`). */
+export type PolicyCaller = {
+    readonly principal: unknown;
+};
+/**
+ * The principal a call's options name (`{ as }`), or `undefined` when they name
+ * none. `null` is a principal: the anonymous one.
+ */
+export declare function callerOf(options: unknown): PolicyCaller | undefined;
+/**
+ * The policy session of one request, or `undefined` when the policy does not
+ * check it. Deriving the principal is server code: a throw is the caller's
+ * to answer as the server's defect.
+ */
+export declare function openRequestPolicy(policy: ResolvedPolicyConfig | undefined, core: AvContractCore, request: {
+    readonly origin: AvRequestOrigin;
+    readonly state: AvState;
+}, caller: PolicyCaller | undefined, executor: AvAdapterOperationExecutor): PolicySession | undefined;
+/**
+ * Policy admission inside its own boundary, as the Framework Validation Layer's
+ * is: a refusal, a defect of the engine or its answers (`A3000`), or an adapter
+ * failure of an `exists` question (`A3001`), answered without any developer
+ * filter; `undefined` when the request goes on to its guards.
+ */
+export declare function admitRequestPolicy(session: PolicySession, core: AvContractCore, active: AvContract, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<AvOperationFailureResponse | undefined>;

package/dist/policy/policy-request.js

@@ -0,0 +1,52 @@
+import { AdapterBoundary, sanitizeOperationFailure, } from "../runtime/error-boundary.js";
+import { admitByPolicy, admitWriteByPolicy } from "./policy-admission.js";
+import { openPolicySession } from "./policy-session.js";
+export function callerOf(options) {
+    if (typeof options !== "object" || options === null) {
+        return undefined;
+    }
+    let principal;
+    try {
+        principal = options.as;
+    }
+    catch {
+        return undefined;
+    }
+    return principal === undefined ? undefined : { principal };
+}
+export function openRequestPolicy(policy, core, request, caller, executor) {
+    if (policy === undefined) {
+        return undefined;
+    }
+    let principal;
+    if (caller !== undefined) {
+        principal = caller.principal;
+    }
+    else if (request.origin === "application") {
+        return undefined;
+    }
+    else {
+        principal = policy.principal({
+            $state: request.state,
+            $origin: request.origin,
+        });
+    }
+    return openPolicySession(policy, core, principal, request.origin, {
+        executor,
+        boundary: new AdapterBoundary(),
+    });
+}
+export async function admitRequestPolicy(session, core, active, request, args, report, view) {
+    try {
+        const refused = await admitByPolicy(session, core, active, request, args);
+        if (refused !== undefined) {
+            return refused;
+        }
+        return request.family === "find"
+            ? undefined
+            : await admitWriteByPolicy(session, core, request, args);
+    }
+    catch (error) {
+        return sanitizeOperationFailure(error, session.execution.boundary.originOf(error), report, view);
+    }
+}

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

@@ -0,0 +1,83 @@
+import type { AvAdapterOperationExecutor } from "../adapters/adapter-operation-executor.interface.js";
+import type { ResolvedPolicyConfig } from "../config/config.resolver.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvContractCore } from "../contracts/contract.js";
+import type { AdapterBoundary } from "../runtime/error-boundary.js";
+import type { PolicyCondition } from "./policy-condition.js";
+import type { AvPolicyWhere } from "./policy-engine.js";
+/** An action a policy question names. */
+export type PolicyAction = "read" | "create" | "update" | "delete";
+/** `fieldsOf`'s answer, held: the names read into sets once. */
+export type PolicyFields = {
+    /** `always` was `"all"`: every field that is not governed. */
+    readonly all: boolean;
+    /** The fields named in `always`, and those granted on every row. */
+    readonly listed: ReadonlySet<string>;
+    /** Each field readable on some rows only, and the condition those rows meet. */
+    readonly perRow: ReadonlyMap<string, AvPolicyWhere>;
+};
+/**
+ * A policy answer core cannot use: a fragment the Core Contract refuses, or an
+ * answer of the wrong shape. The engine is server code, so this is the server's
+ * defect (`A3000`), never the caller's.
+ */
+export declare class PolicyDefectError extends Error {
+    readonly name = "PolicyDefectError";
+}
+/** Where `exists` runs: an executor, and the boundary its failures are classified by. */
+export type PolicyExecution = {
+    readonly executor: AvAdapterOperationExecutor;
+    readonly boundary: AdapterBoundary;
+};
+/** One request's policy questions and answers. */
+export type PolicySession = {
+    readonly principal: unknown;
+    readonly origin: AvRequestOrigin;
+    /** Where its `exists` runs now. */
+    readonly execution: PolicyExecution;
+    /** Whether the principal may run `action` on `resource` (`can`). */
+    can(resource: string, action: PolicyAction, row?: Readonly<Record<string, unknown>>): Promise<boolean>;
+    /** The rows the principal may `action` (`scopeOf`), checked. */
+    scope(resource: string, action: "read" | "update" | "delete"): Promise<PolicyCondition>;
+    /** The fields the principal may read or write (`fieldsOf`), checked. */
+    fields(resource: string, access: "read" | "write"): Promise<PolicyFields>;
+    /** Whether a row of `resource` meets `where`: core's own question, unchecked. */
+    exists(resource: string, where: AvPolicyWhere): Promise<boolean>;
+    /**
+     * The rows of `resource` meeting `where`, the scalar fields `select` names
+     * only: core's own read, unchecked, never cached (a write may change them).
+     */
+    rows(resource: string, where: AvPolicyWhere, select: readonly string[]): Promise<readonly Readonly<Record<string, unknown>>[]>;
+    /** Whether the engine lists `action` on `resource` in `afterChecks`. */
+    checksAfter(resource: string, action: "update"): boolean;
+    /**
+     * Notes a field a create sends that the principal may write on some rows
+     * only, with its grant: admission sees what the caller sent, and the row it
+     * creates is checked against the grant after the insert.
+     */
+    grantCreate(field: string, grant: AvPolicyWhere): void;
+    /** The grants admission noted for the fields a create sends, by field. */
+    createGrants(): ReadonlyMap<string, AvPolicyWhere>;
+    /** The same session, its `exists` running on `execution`. */
+    on(execution: PolicyExecution): PolicySession;
+    /**
+     * The same session with no `exists` answer kept: a write changed the rows,
+     * so a question asked before it may answer differently now.
+     */
+    renewed(): PolicySession;
+};
+/**
+ * Opens the policy session of one request: `principal` under `origin`, its
+ * `exists` on `execution` until {@link PolicySession.on} moves it.
+ */
+export declare function openPolicySession(policy: ResolvedPolicyConfig, core: AvContractCore, principal: unknown, origin: AvRequestOrigin, execution: PolicyExecution): PolicySession;
+/**
+ * Whether `fields` lets the principal use `field` of `resource` on every row it
+ * reaches: listed in `always`, or covered by `"all"` when it is not governed.
+ */
+export declare function alwaysReadable(core: AvContractCore, resource: string, fields: PolicyFields, field: string): boolean;
+/**
+ * How the principal may use `field`: on every row it reaches, on the rows a
+ * grant names, or not at all.
+ */
+export declare function fieldAccess(core: AvContractCore, resource: string, fields: PolicyFields, field: string): "always" | AvPolicyWhere | "never";