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

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

@@ -0,0 +1,93 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+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 { AvPolicyEngine, AvPolicyWhere } from "./policy-engine.js";
+/**
+ * What `fieldsOf` is asked about, beside the question every method states:
+ * reading, or writing by one action. Read from the engine's own signature,
+ * which writes the union inline (see `AvPolicyEngine.fieldsOf`).
+ */
+export type PolicyFieldsAccess = Parameters<AvPolicyEngine["fieldsOf"]>[0] extends infer Question ? Question extends unknown ? Pick<Question, Extract<keyof Question, "access" | "action">> : never : never;
+/** 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 by one action (`fieldsOf`),
+     * checked.
+     */
+    fields(resource: string, access: PolicyFieldsAccess): 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, model: AvAdapterModel, 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";

package/dist/policy/policy-session.js

@@ -0,0 +1,235 @@
+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";
+export 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);
+}
+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: validation.arguments,
+        }, "application")
+        : 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 { always, perRow } = answer;
+    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) {
+            const answer = await engine.can({
+                principal,
+                origin,
+                resource,
+                action,
+                ...(row === undefined ? {} : { row }),
+                exists: engineExists,
+            });
+            if (typeof answer !== "boolean") {
+                throw new PolicyDefectError(`can(${resource}, ${action}) must answer true or false.`);
+            }
+            return answer;
+        },
+        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 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);
+        },
+        on(next) {
+            return sessionOn(policy, core, model, principal, origin, next, caches);
+        },
+        renewed() {
+            return sessionOn(policy, core, model, principal, origin, execution, {
+                ...caches,
+                exists: new WeakMap(),
+            });
+        },
+    };
+}
+export 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,8 @@
+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: every problem, naming the Resource or the rule, or none.
+ */
+export declare function policyStartupDiagnostics(core: AvContractCore, policy: ResolvedPolicyConfig): readonly AvConfigDiagnostic[];

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

@@ -0,0 +1,104 @@
+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, governed) {
+    const diagnostics = [];
+    for (const [resourceName, names] of Object.entries(governed)) {
+        const path = `policy.engine.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, afterChecks) {
+    return Object.keys(afterChecks).flatMap((resourceName) => {
+        const path = `policy.engine.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, paths) {
+    const diagnostics = [];
+    for (const [rule, list] of Object.entries(paths)) {
+        const at = `policy.engine.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;
+}
+export function policyStartupDiagnostics(core, policy) {
+    return [
+        ...governedDiagnostics(core, policy.governed),
+        ...pathDiagnostics(core, policy.paths),
+        ...afterCheckDiagnostics(core, policy.afterChecks),
+    ];
+}

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

@@ -0,0 +1,37 @@
+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 unique update holding nested writes whose adapter call failed: the miss's
+     * answer when its row is outside the scopes (an adapter may fail the nested
+     * write there instead of answering the miss), `undefined` when the failure
+     * stands.
+     */
+    readonly failedMiss?: () => 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>;