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

package/dist/policy/policy-reference-write.runtime.js

@@ -0,0 +1,336 @@
+import { lookupResource } from "../contracts/contract-lookup.js";
+import { advertisedDirectivesAt, } from "../contracts/field.js";
+import { writeScopeOf } from "../contracts/resource-operations.js";
+import { LOOPBACK_WRITE_SCOPE, NESTED_WRITE_SCOPE, TO_MANY_UPDATE_WRITE_SCOPE, } from "../operations/write-scope.resolver.js";
+import { isPlainRecord, isRecord } from "../runtime/record.guard.js";
+import { policyRefusal } from "./policy-admission.js";
+import { allOf, everyOf, noneOf, someOf, whereOf, } from "./policy-condition.js";
+import { NamedRows } from "./policy-named-rows.js";
+const ownedOf = new WeakMap();
+function resourceOf(model, resource) {
+    return Object.hasOwn(model.resources, resource)
+        ? model.resources[resource]
+        : undefined;
+}
+function relationOf(model, resource, name) {
+    const fields = resourceOf(model, resource)?.fields ?? {};
+    const field = Object.hasOwn(fields, name) ? fields[name] : undefined;
+    return field?.kind === "relation" ? field : undefined;
+}
+function isIdentifier(model, resource, fields) {
+    return (resourceOf(model, resource)?.identifiers ?? []).some((identifier) => identifier.length === fields.length &&
+        identifier.every((field) => fields.includes(field)));
+}
+function ownedReferences(model, resource) {
+    let byResource = ownedOf.get(model);
+    if (byResource === undefined) {
+        byResource = new Map();
+        ownedOf.set(model, byResource);
+    }
+    let owned = byResource.get(resource);
+    if (owned === undefined) {
+        const relations = Object.entries(resourceOf(model, resource)?.fields ?? {}).flatMap(([name, field]) => {
+            const relation = field.kind === "relation" ? field : undefined;
+            return relation !== undefined &&
+                typeof relation.target === "string" &&
+                Array.isArray(relation.referenceFields) &&
+                relation.referenceFields.length > 0
+                ? [{ name, relation, fields: relation.referenceFields }]
+                : [];
+        });
+        const holders = new Map();
+        for (const { fields } of relations) {
+            for (const field of fields) {
+                holders.set(field, (holders.get(field) ?? 0) + 1);
+            }
+        }
+        owned = relations.map(({ name, relation, fields }) => {
+            const references = relation.references;
+            return {
+                name,
+                relation,
+                target: relation.target,
+                fields,
+                references,
+                shared: fields.some((field) => (holders.get(field) ?? 0) > 1),
+                addressable: references !== undefined &&
+                    references.length === fields.length &&
+                    isIdentifier(model, relation.target, references),
+            };
+        });
+        byResource.set(resource, owned);
+    }
+    return owned;
+}
+function walk(model, record, at, visit) {
+    let rebuilt;
+    for (const [key, value] of Object.entries(record)) {
+        const relation = isRecord(value)
+            ? relationOf(model, at.resource, key)
+            : undefined;
+        if (relation === undefined || !isRecord(value)) {
+            continue;
+        }
+        const nested = (one, stage, scope = NESTED_WRITE_SCOPE) => isRecord(one)
+            ? walk(model, one, { resource: relation.target, stage, scope, via: relation.inverse }, visit)
+            : one;
+        const each = (operand, entry) => Array.isArray(operand)
+            ? operand.map((one) => (isRecord(one) ? entry(one) : one))
+            : isRecord(operand)
+                ? entry(operand)
+                : operand;
+        const directives = {};
+        for (const [directive, operand] of Object.entries(value)) {
+            switch (directive) {
+                case "$create":
+                    directives[directive] = each(operand, (one) => nested(one, "create"));
+                    break;
+                case "$connectOrCreate":
+                    directives[directive] = each(operand, (one) => ({
+                        ...one,
+                        create: nested(one.create, "create"),
+                    }));
+                    break;
+                case "$upsert":
+                    directives[directive] = each(operand, (one) => ({
+                        ...one,
+                        create: nested(one.create, "create"),
+                        update: nested(one.update, "update"),
+                    }));
+                    break;
+                case "$update":
+                    directives[directive] = each(operand, (one) => ({
+                        ...one,
+                        data: nested(one.data, "update", relation.cardinality === "many"
+                            ? TO_MANY_UPDATE_WRITE_SCOPE
+                            : NESTED_WRITE_SCOPE),
+                    }));
+                    break;
+                default:
+                    directives[directive] = operand;
+            }
+        }
+        rebuilt ??= { ...record };
+        rebuilt[key] = directives;
+    }
+    return visit(rebuilt ?? record, at);
+}
+function writtenReferences(model, record, resource) {
+    return ownedReferences(model, resource).flatMap((owned) => {
+        const written = owned.fields.filter((field) => Object.hasOwn(record, field) && record[field] !== undefined);
+        if (written.length === 0) {
+            return [];
+        }
+        const values = written.map((field) => record[field]);
+        if (values.some((value) => value === null)) {
+            return [
+                [
+                    owned,
+                    values.every((value) => value === null) &&
+                        written.length === owned.fields.length
+                        ? { kind: "null" }
+                        : { kind: "partial" },
+                ],
+            ];
+        }
+        const references = owned.references;
+        return [
+            [
+                owned,
+                written.length !== owned.fields.length ||
+                    references === undefined ||
+                    references.length !== owned.fields.length ||
+                    values.some(isPlainRecord)
+                    ? { kind: "unstated" }
+                    : { kind: "value", values },
+            ],
+        ];
+    });
+}
+function offers(owned, at, directive) {
+    const scope = owned.name === at.via ? LOOPBACK_WRITE_SCOPE : at.scope;
+    return (advertisedDirectivesAt(owned.relation.capabilities[at.stage], scope)?.includes(directive) === true);
+}
+function linkable(record, at, written) {
+    return written.every(([owned, how]) => {
+        if (owned.shared || record[owned.name] !== undefined) {
+            return false;
+        }
+        switch (how.kind) {
+            case "value":
+                return owned.addressable && offers(owned, at, "$connect");
+            case "null":
+                return at.stage === "update" && offers(owned, at, "$disconnect");
+            default:
+                return false;
+        }
+    });
+}
+export function isHeldTarget(core, unheld, target) {
+    return lookupResource(core, target) !== undefined && !unheld.includes(target);
+}
+export function heldTargetsOf(core, unheld) {
+    return Object.freeze(Object.keys(core.resources).filter((target) => isHeldTarget(core, unheld, target)));
+}
+function heldScope(held, reads, target) {
+    if (!held(target)) {
+        return true;
+    }
+    const read = reads.get(target);
+    if (read === undefined) {
+        throw new Error(`policy: the reference to Resource "${target}" was not held before the write.`);
+    }
+    return read;
+}
+function holds(held, reads, written) {
+    return written.some(([owned, how]) => (how.kind === "value" || how.kind === "unstated") &&
+        heldScope(held, reads, owned.target) !== true);
+}
+function asLinks(held, reads, record, written) {
+    const linked = { ...record };
+    for (const [owned, how] of written) {
+        for (const field of owned.fields) {
+            delete linked[field];
+        }
+        if (how.kind === "null") {
+            linked[owned.name] = { $disconnect: true };
+            continue;
+        }
+        if (how.kind !== "value") {
+            continue;
+        }
+        const selector = Object.fromEntries((owned.references ?? []).map((reference, index) => [
+            reference,
+            how.values[index],
+        ]));
+        const read = heldScope(held, reads, owned.target);
+        if (read !== true && read !== false) {
+            selector.AND = [whereOf(read)];
+        }
+        linked[owned.name] = { $connect: selector };
+    }
+    return linked;
+}
+function outsideRead(target) {
+    return policyRefusal(`The policy does not allow this write to link a row of Resource "${target}" outside what the caller may read.`);
+}
+export async function heldReferences(session, core, model, request, sites) {
+    const resource = request.resource;
+    const held = (target) => isHeldTarget(core, session.unheld, target);
+    const family = resourceOf(model, resource)?.operations?.[request.family];
+    const scope = writeScopeOf(isRecord(family) ? family[request.variant] : undefined);
+    const top = (stage) => ({
+        resource,
+        stage,
+        scope,
+        via: undefined,
+    });
+    const records = sites.flatMap(({ stage, records }) => records.filter(isRecord).map((record) => [record, top(stage)]));
+    const targets = new Set();
+    for (const [record, at] of records) {
+        walk(model, record, at, (one, where) => {
+            for (const [owned, how] of writtenReferences(model, one, where.resource)) {
+                if (how.kind === "value" || how.kind === "unstated") {
+                    targets.add(owned.target);
+                }
+            }
+            return one;
+        });
+    }
+    const reads = new Map();
+    for (const target of targets) {
+        if (held(target)) {
+            reads.set(target, await session.scope(target, "read"));
+        }
+    }
+    let refusal;
+    let linked = false;
+    const asked = new Map();
+    const named = new Map();
+    const hold = (record, at) => {
+        const written = writtenReferences(model, record, at.resource);
+        if (refusal !== undefined || !holds(held, reads, written)) {
+            return record;
+        }
+        for (const [owned, how] of written) {
+            const read = how.kind === "value" || how.kind === "unstated"
+                ? heldScope(held, reads, owned.target)
+                : true;
+            if (read === true) {
+                continue;
+            }
+            if (how.kind === "unstated") {
+                refusal = policyRefusal(`The policy holds a reference this write sends to Resource "${owned.target}" to what the caller may read, and the write does not state the row it links (send every field of the reference as a value).`);
+                return record;
+            }
+            if (read === false) {
+                refusal = outsideRead(owned.target);
+                return record;
+            }
+        }
+        if (linkable(record, at, written)) {
+            linked = true;
+            return record;
+        }
+        for (const [owned, how] of written) {
+            if (how.kind !== "value" ||
+                heldScope(held, reads, owned.target) === true) {
+                continue;
+            }
+            const read = heldScope(held, reads, owned.target);
+            const selector = everyOf((owned.references ?? []).map((reference, index) => ({
+                [reference]: { equals: how.values[index] },
+            })));
+            if (owned.addressable && selector !== true && selector !== false) {
+                let rows = named.get(owned.target);
+                if (rows === undefined) {
+                    rows = new NamedRows();
+                    named.set(owned.target, rows);
+                }
+                rows.add(selector, read);
+                continue;
+            }
+            let rows = asked.get(owned.target);
+            if (rows === undefined) {
+                rows = [];
+                asked.set(owned.target, rows);
+            }
+            rows.push(selector);
+        }
+        return record;
+    };
+    for (const [record, at] of records) {
+        walk(model, record, at, hold);
+    }
+    if (refusal !== undefined) {
+        return { kind: "refused", response: refusal };
+    }
+    for (const [target, rows] of named) {
+        if (rows.size > 0 && !(await rows.within(session, target))) {
+            return { kind: "refused", response: outsideRead(target) };
+        }
+    }
+    for (const [target, rows] of asked) {
+        const outside = allOf(someOf(rows), noneOf(heldScope(held, reads, target)));
+        if (outside !== false && (await session.exists(target, whereOf(outside)))) {
+            return { kind: "refused", response: outsideRead(target) };
+        }
+    }
+    const link = (record, at) => {
+        const written = writtenReferences(model, record, at.resource);
+        return holds(held, reads, written) && linkable(record, at, written)
+            ? asLinks(held, reads, record, written)
+            : record;
+    };
+    return {
+        kind: "held",
+        linked,
+        apply: (value, stage) => {
+            if (!linked) {
+                return value;
+            }
+            const one = (record) => isRecord(record) ? walk(model, record, top(stage), link) : record;
+            return Array.isArray(value) ? value.map(one) : one(value);
+        },
+    };
+}

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

@@ -0,0 +1,72 @@
+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 { 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; a promise of it when the principal arrives as one. Deriving the
+ * principal is server code: a throw, or a rejection, 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, adapter: AvAdapterOperationExecutor & {
+    readonly model: AvAdapterModel;
+}): PolicySession | undefined | Promise<PolicySession | undefined>;
+/**
+ * The principal a remote request runs as, derived once from its state, or
+ * `undefined` when no policy checks it; a promise of it when the principal
+ * arrives as one. A throw, or a rejection, is the caller's to answer as the
+ * server's defect. Under a held state ({@link holdRequestPrincipal}) it is the
+ * principal derived the first time, however often it is asked.
+ */
+export declare function derivePolicyCaller(policy: ResolvedPolicyConfig | undefined, request: {
+    readonly origin: AvRequestOrigin;
+    readonly state: AvState;
+}): PolicyCaller | undefined | Promise<PolicyCaller>;
+/**
+ * Derives and holds `request`'s origin's principal from a held state that
+ * holds none yet; nothing for a state no host held, or for an origin the
+ * policy derives no principal for. Never throws and never rejects: the
+ * request that names its principal is not answered by it. A throw holds
+ * nothing; a rejection is held, observed here, and answers the requests that
+ * later read it.
+ */
+export declare function holdFirstPrincipal(policy: ResolvedPolicyConfig | undefined, request: {
+    readonly origin: AvRequestOrigin;
+    readonly state: AvState;
+}): void;
+/**
+ * Holds `state` as one request's: every request run under this object reads
+ * its principal once, the first time one is derived from it, until the state
+ * is held again. A host calls it once per request, on the state it seeds once
+ * and shares between that request's calls, before any of them runs. Anything
+ * that is not an object is ignored: no request runs under it.
+ */
+export declare function holdRequestPrincipal(state: unknown): void;
+/**
+ * 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,115 @@
+import { AdapterBoundary, sanitizeOperationFailure, } from "../runtime/error-boundary.js";
+import { isThenable } from "../runtime/thenable.guard.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, adapter) {
+    if (policy === undefined) {
+        return undefined;
+    }
+    if (caller !== undefined) {
+        holdFirstPrincipal(policy, request);
+    }
+    const settled = caller ?? derivePolicyCaller(policy, request);
+    if (settled === undefined) {
+        return undefined;
+    }
+    return settled instanceof Promise
+        ? settled.then(({ principal }) => sessionOf(policy, core, request.origin, adapter, principal))
+        : sessionOf(policy, core, request.origin, adapter, settled.principal);
+}
+export function derivePolicyCaller(policy, request) {
+    if (policy === undefined || request.origin === "application") {
+        return undefined;
+    }
+    const held = heldOf(policy, request.state);
+    if (held === undefined) {
+        return principalOf(policy, request);
+    }
+    const known = held.get(request.origin);
+    if (known !== undefined) {
+        return known;
+    }
+    const derived = principalOf(policy, request);
+    held.set(request.origin, derived);
+    return derived;
+}
+export function holdFirstPrincipal(policy, request) {
+    if (policy === undefined || request.origin === "application") {
+        return;
+    }
+    const held = heldOf(policy, request.state);
+    if (held === undefined || held.has(request.origin)) {
+        return;
+    }
+    let derived;
+    try {
+        derived = principalOf(policy, request);
+    }
+    catch {
+        return;
+    }
+    if (derived instanceof Promise) {
+        derived.catch(() => undefined);
+    }
+    held.set(request.origin, derived);
+}
+function heldOf(policy, state) {
+    const held = HELD_PRINCIPALS.get(state);
+    if (held === undefined) {
+        return undefined;
+    }
+    let byOrigin = held.get(policy);
+    if (byOrigin === undefined) {
+        byOrigin = new Map();
+        held.set(policy, byOrigin);
+    }
+    return byOrigin;
+}
+function principalOf(policy, request) {
+    const principal = policy.principal({
+        $state: request.state,
+        $origin: request.origin,
+    });
+    return isThenable(principal)
+        ? Promise.resolve(principal).then((settled) => ({ principal: settled }))
+        : { principal };
+}
+const HELD_PRINCIPALS = new WeakMap();
+export function holdRequestPrincipal(state) {
+    if (typeof state === "object" && state !== null) {
+        HELD_PRINCIPALS.set(state, new Map());
+    }
+}
+function sessionOf(policy, core, origin, adapter, principal) {
+    return openPolicySession(policy, core, adapter.model, principal, origin, {
+        executor: adapter,
+        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,106 @@
+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>;
+};
+/** Where `exists` runs: an executor, and the boundary its failures are classified by. */
+export type PolicyExecution = {
+    readonly executor: AvAdapterOperationExecutor;
+    readonly boundary: AdapterBoundary;
+};
+/**
+ * A changed row as it was before its update, as the after check states it:
+ * the row, and the grants the engine said covered it then (`grantsOf`), when
+ * it answers that question.
+ */
+export type PolicyBefore = {
+    readonly row: Readonly<Record<string, unknown>>;
+    readonly grants?: readonly string[];
+};
+/** 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`): about `row`
+     * when given, and on an update's after check, the row `before` it with the
+     * grants that covered it then, when the engine answered them.
+     */
+    can(resource: string, action: PolicyAction, row?: Readonly<Record<string, unknown>>, before?: PolicyBefore): Promise<boolean>;
+    /**
+     * The grants that cover `row` of `resource` before an update (`grantsOf`),
+     * checked; `undefined` when the engine answers no such question.
+     */
+    grants(resource: string, row: Readonly<Record<string, unknown>>): Promise<readonly string[] | undefined>;
+    /** 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>;
+    /**
+     * How many rows of `resource` meet `where`: core's own question, unchecked,
+     * never cached; `undefined` where the Core Contract offers neither a count
+     * nor a list of the Resource.
+     */
+    count(resource: string, where: AvPolicyWhere): Promise<number | undefined>;
+    /**
+     * 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;
+    /** The Resources the engine lists in `unheld`, read once at construction. */
+    readonly unheld: readonly string[];
+    /**
+     * 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;
+/**
+ * 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";