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

package/dist/policy/policy-session.js

@@ -0,0 +1,295 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { validateOperationArguments } from "../operations/operation-validator-core.js";
+import { normalizeOperationScalarValues } from "../runtime/scalar-runtime.js";
+import { encodeOperationArgumentsForWire } from "../transactions/operation-arguments-encoder.js";
+class PolicyDefectError extends Error {
+    name = "PolicyDefectError";
+}
+function isEmptyRecord(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 0);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const FRAGMENT_WIRE_ORIGIN = "client";
+function checkedFragment(core, resource, where, what) {
+    if (!isRecord(where)) {
+        throw new PolicyDefectError(`${what} must be a where object.`);
+    }
+    const request = {
+        resource,
+        family: "find",
+        variant: "many",
+        arguments: { where },
+    };
+    const validation = validateOperationArguments(core, request);
+    const normalized = validation.ok
+        ? normalizeOperationScalarValues(core, {
+            ...request,
+            arguments: encodeOperationArgumentsForWire(core, request, validation.arguments),
+        }, FRAGMENT_WIRE_ORIGIN)
+        : validation;
+    if (!normalized.ok) {
+        const issues = normalized.issues
+            .map((issue) => `${issue.code} at ${(issue.path ?? []).slice(2).join(".") || "where"}: ${issue.message}`)
+            .join("; ");
+        throw new PolicyDefectError(`${what} is no where of Resource "${resource}" in the Core Contract (${issues}).`);
+    }
+    return normalized.arguments.where;
+}
+function conditionOf(core, resource, answer, what) {
+    if (typeof answer === "boolean") {
+        return answer;
+    }
+    if (isEmptyRecord(answer)) {
+        return true;
+    }
+    return checkedFragment(core, resource, answer, what);
+}
+function fieldsAnswer(core, resource, answer) {
+    const what = `fieldsOf(${resource})`;
+    if (!isRecord(answer)) {
+        throw new PolicyDefectError(`${what} must answer { always, perRow }.`);
+    }
+    const { perRow } = answer;
+    const always = Array.isArray(answer.always)
+        ? Array.from(answer.always)
+        : answer.always;
+    if (always !== "all" &&
+        !(Array.isArray(always) && always.every((name) => typeof name === "string"))) {
+        throw new PolicyDefectError(`${what}.always must be "all" or a list of field names.`);
+    }
+    if (!isRecord(perRow)) {
+        throw new PolicyDefectError(`${what}.perRow must be an object.`);
+    }
+    const listed = new Set(always === "all" ? [] : always);
+    const grants = new Map();
+    for (const [field, grant] of Object.entries(perRow)) {
+        if (listed.has(field) || grant === undefined) {
+            continue;
+        }
+        const condition = conditionOf(core, resource, grant, `${what}.perRow.${field}`);
+        if (condition === true) {
+            listed.add(field);
+        }
+        else if (condition !== false) {
+            grants.set(field, condition);
+        }
+    }
+    return { all: always === "all", listed, perRow: grants };
+}
+function questionKey(resource, where) {
+    try {
+        return `${resource}\u0000${JSON.stringify(where, (_key, value) => typeof value === "bigint" ? `#bigint(${value})` : value)}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function existsOperation(core, model, resource, where) {
+    const contract = lookupResource(core, resource);
+    const identifier = adapterPrimaryIdentifier(model, resource);
+    const first = contract?.operations.find?.first !== undefined;
+    return first && identifier.length > 0
+        ? {
+            resource,
+            family: "find",
+            variant: "first",
+            arguments: { where, select: [...identifier] },
+        }
+        : {
+            resource,
+            family: "find",
+            variant: "count",
+            arguments: { where },
+        };
+}
+export function openPolicySession(policy, core, model, principal, origin, execution) {
+    const caches = {
+        scopes: new Map(),
+        createGrants: new Map(),
+        fields: new Map(),
+        exists: new WeakMap(),
+    };
+    return sessionOn(policy, core, model, principal, origin, execution, caches);
+}
+function sessionOn(policy, core, model, principal, origin, execution, caches) {
+    const { engine } = policy;
+    const exists = (resource, where) => {
+        const key = questionKey(resource, where);
+        let answers = caches.exists.get(execution.executor);
+        if (answers === undefined) {
+            answers = new Map();
+            caches.exists.set(execution.executor, answers);
+        }
+        const known = key === undefined ? undefined : answers.get(key);
+        if (known !== undefined) {
+            return known;
+        }
+        const operation = existsOperation(core, model, resource, where);
+        const answer = execution.boundary
+            .execute(() => execution.executor.execute(operation))
+            .then((result) => typeof result === "number" ? result > 0 : result != null);
+        if (key !== undefined) {
+            answers.set(key, answer);
+        }
+        return answer;
+    };
+    const engineExists = async (resource, where) => {
+        if (typeof resource !== "string" ||
+            lookupResource(core, resource) === undefined) {
+            throw new PolicyDefectError(`exists was asked about "${String(resource)}", which is no Resource of the Core Contract.`);
+        }
+        const condition = conditionOf(core, resource, where, "exists's where");
+        if (typeof condition === "boolean") {
+            return exists(resource, {});
+        }
+        return exists(resource, condition);
+    };
+    return {
+        principal,
+        origin,
+        execution,
+        async can(resource, action, row, before) {
+            const answer = await engine.can({
+                principal,
+                origin,
+                resource,
+                action,
+                ...(row === undefined ? {} : { row }),
+                ...(before === undefined ? {} : { before: before.row }),
+                ...(before?.grants === undefined
+                    ? {}
+                    : { beforeGrants: before.grants }),
+                exists: engineExists,
+            });
+            if (typeof answer !== "boolean") {
+                throw new PolicyDefectError(`can(${resource}, ${action}) must answer true or false.`);
+            }
+            return answer;
+        },
+        async grants(resource, row) {
+            if (engine.grantsOf === undefined) {
+                return undefined;
+            }
+            const answer = await engine.grantsOf({
+                principal,
+                origin,
+                resource,
+                action: "update",
+                row,
+                exists: engineExists,
+            });
+            const keys = Array.isArray(answer)
+                ? Array.from(answer)
+                : undefined;
+            if (keys === undefined || !keys.every((key) => typeof key === "string")) {
+                throw new PolicyDefectError(`grantsOf(${resource}) must answer a list of strings.`);
+            }
+            return Object.freeze(keys);
+        },
+        scope(resource, action) {
+            const key = `${resource}\u0000${action}`;
+            let scope = caches.scopes.get(key);
+            if (scope === undefined) {
+                scope = Promise.resolve()
+                    .then(() => engine.scopeOf({ principal, origin, resource, action }))
+                    .then((answer) => conditionOf(core, resource, answer, `scopeOf(${resource}, ${action})`));
+                caches.scopes.set(key, scope);
+            }
+            return scope;
+        },
+        fields(resource, access) {
+            const key = `${resource}\u0000${access.access}\u0000${access.access === "write" ? access.action : ""}`;
+            let fields = caches.fields.get(key);
+            if (fields === undefined) {
+                fields = Promise.resolve()
+                    .then(() => engine.fieldsOf({ principal, origin, resource, ...access }))
+                    .then((answer) => fieldsAnswer(core, resource, answer));
+                caches.fields.set(key, fields);
+            }
+            return fields;
+        },
+        exists,
+        async count(resource, where) {
+            const find = lookupResource(core, resource)?.operations.find;
+            const identifier = adapterPrimaryIdentifier(model, resource);
+            const operation = find?.count !== undefined
+                ? {
+                    resource,
+                    family: "find",
+                    variant: "count",
+                    arguments: { where },
+                }
+                : find?.many !== undefined && identifier.length > 0
+                    ? {
+                        resource,
+                        family: "find",
+                        variant: "many",
+                        arguments: { where, select: [...identifier] },
+                    }
+                    : undefined;
+            if (operation === undefined) {
+                return undefined;
+            }
+            const answer = await execution.boundary.execute(() => execution.executor.execute(operation));
+            if (typeof answer === "number") {
+                return answer;
+            }
+            if (Array.isArray(answer)) {
+                return answer.length;
+            }
+            throw new PolicyDefectError(`The adapter answered the count of Resource "${resource}" with no number.`);
+        },
+        async rows(resource, where, select) {
+            if (lookupResource(core, resource)?.operations.find?.many === undefined) {
+                throw new PolicyDefectError(`The policy needs the rows of Resource "${resource}", and its Core Contract offers no find.many.`);
+            }
+            const operation = {
+                resource,
+                family: "find",
+                variant: "many",
+                arguments: { where, select: [...select] },
+            };
+            const answer = await execution.boundary.execute(() => execution.executor.execute(operation));
+            return Array.isArray(answer)
+                ? answer.filter((row) => isRecord(row))
+                : [];
+        },
+        grantCreate(field, grant) {
+            caches.createGrants.set(field, grant);
+        },
+        createGrants() {
+            return caches.createGrants;
+        },
+        checksAfter(resource, action) {
+            return (Object.hasOwn(policy.afterChecks, resource) &&
+                policy.afterChecks[resource]?.includes(action) === true);
+        },
+        unheld: policy.unheld,
+        on(next) {
+            return sessionOn(policy, core, model, principal, origin, next, caches);
+        },
+        renewed() {
+            return sessionOn(policy, core, model, principal, origin, execution, {
+                ...caches,
+                exists: new WeakMap(),
+            });
+        },
+    };
+}
+function alwaysReadable(core, resource, fields, field) {
+    return (fields.listed.has(field) ||
+        (fields.all &&
+            lookupField(lookupResource(core, resource), field)?.governed !== true));
+}
+export function fieldAccess(core, resource, fields, field) {
+    if (alwaysReadable(core, resource, fields, field)) {
+        return "always";
+    }
+    return fields.perRow.get(field) ?? "never";
+}

package/dist/policy/policy-startup.validator.d.ts

@@ -0,0 +1,10 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { ResolvedPolicyConfig } from "../config/config.resolver.js";
+import type { AvConfigDiagnostic } from "../config/config-diagnostic.js";
+import type { AvContractCore } from "../contracts/contract.js";
+/**
+ * The policy's governed set, rule paths and after checks checked against the
+ * Core Contract, and its unheld Resources against the data source's model:
+ * every problem, naming the Resource or the rule, or none.
+ */
+export declare function policyStartupDiagnostics(core: AvContractCore, policy: ResolvedPolicyConfig, model: AvAdapterModel): readonly AvConfigDiagnostic[];

package/dist/policy/policy-startup.validator.js

@@ -0,0 +1,112 @@
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+const TO_MANY_OPERATORS = new Set(["some", "every", "none"]);
+function invalid(path, message) {
+    return { code: "CONFIG_INVALID_VALUE", path, message };
+}
+function governedDiagnostics(core, { at, governed }) {
+    const diagnostics = [];
+    for (const [resourceName, names] of Object.entries(governed)) {
+        const path = `${at}.governed.${resourceName}`;
+        const resource = lookupResource(core, resourceName);
+        if (resource === undefined) {
+            diagnostics.push(invalid(path, `"${resourceName}" is no Resource of the Core Contract`));
+            continue;
+        }
+        for (const name of names) {
+            if (lookupField(resource, name) === undefined) {
+                diagnostics.push(invalid(path, `"${name}" is no field or relation of Resource "${resourceName}" in the Core Contract`));
+            }
+        }
+    }
+    return diagnostics;
+}
+function afterCheckDiagnostics(core, { at, afterChecks }) {
+    return Object.keys(afterChecks).flatMap((resourceName) => {
+        const path = `${at}.afterChecks.${resourceName}`;
+        return lookupResource(core, resourceName) === undefined
+            ? [invalid(path, `"${resourceName}" is no Resource of the Core Contract`)]
+            : [];
+    });
+}
+function pathFault(core, path) {
+    const [resourceName, ...segments] = path;
+    let resource = resourceName === undefined ? undefined : lookupResource(core, resourceName);
+    if (resource === undefined) {
+        return `"${resourceName ?? ""}" is no Resource of the Core Contract`;
+    }
+    let current = resourceName;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const field = lookupField(resource, segment);
+        if (field === undefined) {
+            return `"${segment}" is no field or relation of Resource "${current}"`;
+        }
+        const filters = field.capabilities.filter ?? [];
+        if (field.kind === "scalar") {
+            if (filters.length === 0) {
+                return `field "${current}.${segment}" cannot be filtered`;
+            }
+            const operator = segments[index + 1];
+            if (operator !== undefined && !filters.includes(operator)) {
+                return `field "${current}.${segment}" has no filter operator "${operator}"`;
+            }
+            if (index + 2 < segments.length) {
+                return `the path goes on past scalar field "${current}.${segment}"`;
+            }
+            return undefined;
+        }
+        const target = lookupResource(core, field.target);
+        if (target === undefined) {
+            return `relation "${current}.${segment}" leads to no Resource of the Core Contract`;
+        }
+        if (field.cardinality === "many") {
+            const operator = segments[index + 1];
+            if (operator === undefined || !TO_MANY_OPERATORS.has(operator)) {
+                return `to-many relation "${current}.${segment}" must be followed by some, every or none`;
+            }
+            if (!filters.includes(operator)) {
+                return `relation "${current}.${segment}" has no "${operator}" filter`;
+            }
+            index += 1;
+        }
+        else if (index + 1 === segments.length) {
+            return filters.includes("null")
+                ? undefined
+                : `relation "${current}.${segment}" has no null filter`;
+        }
+        else if (!filters.includes("match")) {
+            return `relation "${current}.${segment}" cannot filter its target directly`;
+        }
+        resource = target;
+        current = field.target;
+    }
+    return `the path ends at Resource "${current}", not at a field`;
+}
+function pathDiagnostics(core, policy) {
+    const diagnostics = [];
+    for (const [rule, list] of Object.entries(policy.paths)) {
+        const at = `${policy.at}.paths.${rule}`;
+        for (const path of list) {
+            const fault = pathFault(core, path);
+            if (fault !== undefined) {
+                diagnostics.push(invalid(at, `rule "${rule}" filters on "${path.join(".")}": ${fault}`));
+            }
+        }
+    }
+    return diagnostics;
+}
+function unheldDiagnostics(model, { at, unheld }) {
+    return unheld.flatMap((resourceName) => Object.hasOwn(model.resources, resourceName)
+        ? []
+        : [
+            invalid(`${at}.unheld`, `"${resourceName}" is no Resource of the data source's model`),
+        ]);
+}
+export function policyStartupDiagnostics(core, policy, model) {
+    return [
+        ...governedDiagnostics(core, policy),
+        ...pathDiagnostics(core, policy),
+        ...afterCheckDiagnostics(core, policy),
+        ...unheldDiagnostics(model, policy),
+    ];
+}

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

@@ -0,0 +1,39 @@
+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 } from "../runtime/computed-read-runtime.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type PolicyRead } from "./policy-read.runtime.js";
+import type { PolicySession } from "./policy-session.js";
+/** A write's policy: what the adapter runs, and how a unique write's miss answers. */
+export type PolicyWrite = PolicyRead & {
+    /** A unique write that matched nothing: `A4002` for a row the caller can read, `A2003` otherwise. */
+    readonly miss?: () => Promise<AvOperationFailureResponse>;
+    /**
+     * A write holding nested writes or links whose adapter call failed with `error`:
+     * what the failure answers instead, or `undefined` when it stands. A unique
+     * update's miss when its row is outside the scopes (an adapter may fail the nested
+     * write there instead of answering the miss); the refusal when a row a to-one
+     * `$update` was held to changed before the call, or when the adapter refused a
+     * link held to its target's read scope.
+     */
+    readonly failed?: (error: unknown) => Promise<AvOperationFailureResponse | undefined>;
+};
+/**
+ * Whether a write the policy checks needs an interactive transaction to roll
+ * it back in. Where it has none, {@link enforceWritePolicy} refuses exactly
+ * these writes before they run. `planned` plans the request's read, asked only
+ * when the answer depends on the rows it returns.
+ */
+export declare function writeNeedsTransaction(session: PolicySession, core: AvContractCore, request: AvOperationIdentity & {
+    readonly resource: string;
+}, planned: () => PlannedReadOperation, adapterArguments: unknown): Promise<boolean>;
+/**
+ * One write's policy (see the module comment): the refusal, the answer when it
+ * reaches no row, or what the adapter runs and how its answer is checked.
+ * `inTransaction` says whether the write runs in an interactive transaction a
+ * failed check rolls back.
+ */
+export declare function enforceWritePolicy(session: PolicySession, core: AvContractCore, model: AvAdapterModel, request: AvOperationIdentity & {
+    readonly resource: string;
+}, plan: PlannedReadOperation, adapterArguments: unknown, inTransaction: boolean): Promise<PolicyWrite>;