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

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

@@ -0,0 +1,15 @@
+import type { AvPolicyWhere } from "./policy-engine.js";
+/** A row condition: every row, no row, or a `where` fragment. */
+export type PolicyCondition = boolean | AvPolicyWhere;
+/** Both conditions: a constant folds, two fragments become one `AND`. */
+export declare function allOf(left: PolicyCondition, right: PolicyCondition): PolicyCondition;
+/** Either condition: a constant folds, two fragments become one `OR`. */
+export declare function anyOf(left: PolicyCondition, right: PolicyCondition): PolicyCondition;
+/** Every condition of `conditions`; `true` when there is none. */
+export declare function everyOf(conditions: readonly PolicyCondition[]): PolicyCondition;
+/** Any condition of `conditions`; `false` when there is none. */
+export declare function someOf(conditions: readonly PolicyCondition[]): PolicyCondition;
+/** The negation: a constant flips, a fragment is wrapped in `NOT`. */
+export declare function noneOf(condition: PolicyCondition): PolicyCondition;
+/** A condition as a `where` an `exists` or a read can run: `{}` for every row. */
+export declare function whereOf(condition: Exclude<PolicyCondition, false>): AvPolicyWhere;

package/dist/policy/policy-condition.js

@@ -0,0 +1,36 @@
+export function allOf(left, right) {
+    if (left === false || right === false) {
+        return false;
+    }
+    if (left === true) {
+        return right;
+    }
+    if (right === true) {
+        return left;
+    }
+    return { AND: [left, right] };
+}
+export function anyOf(left, right) {
+    if (left === true || right === true) {
+        return true;
+    }
+    if (left === false) {
+        return right;
+    }
+    if (right === false) {
+        return left;
+    }
+    return { OR: [left, right] };
+}
+export function everyOf(conditions) {
+    return conditions.reduce(allOf, true);
+}
+export function someOf(conditions) {
+    return conditions.reduce(anyOf, false);
+}
+export function noneOf(condition) {
+    return typeof condition === "boolean" ? !condition : { NOT: condition };
+}
+export function whereOf(condition) {
+    return condition === true ? {} : condition;
+}

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

@@ -0,0 +1,205 @@
+import type { AvRequestOrigin } from "../config/config-layer.js";
+/** An answer now or later: every question may be answered asynchronously. */
+type PolicyAnswer<T> = T | Promise<T>;
+/**
+ * A fragment of Aventara's own `where` grammar, as a policy states a row
+ * condition: a scope, a field's per-row grant, or the question an engine's rule
+ * asks through `exists`. It is validated against the Core Contract when it is
+ * used, never the caller's, so it may name a field the caller cannot see
+ * (`ownerId`). A typed literal may be stated in its application form (`Date`,
+ * `AvDecimal`, `bigint`, `Uint8Array`) or in its wire form (an ISO-8601 UTC
+ * string, a decimal string, a base-10 digit string, base64), as a policy read
+ * from JSON states it; either reaches the adapter as the runtime value. One
+ * that does not validate is the server's defect: the request answers `A3000`.
+ */
+export type AvPolicyWhere = {
+    readonly [key: string]: unknown;
+};
+/** What every question to the engine states. */
+type PolicyQuestion = {
+    /** What the configuration's `policy.principal` derived for the request, or the `as` of an application call. */
+    readonly principal: unknown;
+    /** Which layer the request runs under. */
+    readonly origin: AvRequestOrigin;
+    /** The Resource the question is about. */
+    readonly resource: string;
+};
+/**
+ * The policy engine a Framework consults (root configuration `policy.engine`).
+ * Core asks it three questions per request and Resource, and enforces the
+ * answers: the operation (`can`), the rows (`scopeOf`) and the fields
+ * (`fieldsOf`). Every method may answer with a promise.
+ *
+ * `Governed` is the engine's `governed` set, stated by its type so the
+ * application's types leave those fields out of every default projection, as
+ * the Contracts do.
+ */
+export interface AvPolicyEngine<Governed extends {
+    readonly [resource: string]: readonly string[];
+} = {
+    readonly [resource: string]: readonly string[];
+}> {
+    /**
+     * The fields and relations the policy governs, by Resource. Each is left out
+     * of every default projection, for every caller, and is the only trace the
+     * policy leaves in a Contract (a `governed: true` mark). A caller that wants
+     * one names it, and is refused (`A4002`) unless it may read it on every row
+     * it uses it on. Checked against the Core Contract at startup.
+     */
+    readonly governed?: Governed;
+    /**
+     * The relation paths and filter operators the engine's rules filter on, by
+     * the rule's name, each path a list of segments:
+     * `["Note", "campaign", "memberships", "some", "userId", "equals"]`, a
+     * Resource, then its fields and relations (a to-many relation followed by
+     * `some`, `every` or `none`), then the scalar field, then optionally the
+     * filter operator. Checked against the Core Contract at startup: a path it
+     * cannot filter fails construction, naming the rule.
+     */
+    readonly paths?: {
+        readonly [rule: string]: readonly (readonly string[])[];
+    };
+    /**
+     * The writes whose grants carry an `after` condition, by Resource: a row
+     * they change must still meet it once changed (`{ Note: ["update"] }`).
+     * Inside a transaction core asks `can` about each row every checked update
+     * changed, listed or not, and rolls the write back (`A4002`) when one fails.
+     * This list decides where the operation has no interactive transaction:
+     * these updates are refused there (`A4002`), and every other one runs
+     * without the after check. It also decides which after checks carry
+     * `before`, the row as it was before the update (see `can`), and which rows
+     * `grantsOf` is asked about: only these.
+     * Checked against the Core Contract at startup.
+     */
+    readonly afterChecks?: {
+        readonly [resource: string]: readonly "update"[];
+    };
+    /**
+     * The Resources the engine's rules read in conditions and decide no read of. A
+     * written reference to a row of one is not held to the caller's read scope, nor is
+     * a relation directive that links one where the writing row holds the reference
+     * and names the row by the reference's own values (one that names it by another
+     * unique key still is, or the link would tell the caller its identifier): the
+     * write's own grant decides which row may be linked (its `can`, and the after
+     * check `afterChecks` lists). Every read of them is still decided by `scopeOf`,
+     * and a link that changes a row of one is still held to its update scope. Read
+     * once, when the Framework is built: a name the data source's model does not have
+     * fails construction. An engine that does decide reads of a Resource it lists lets
+     * a write link a row of it the caller cannot read.
+     */
+    readonly unheld?: readonly string[];
+    /**
+     * Whether the principal may run `action` on `resource`. Asked once per
+     * request before any developer stage, without a row: `false` refuses the
+     * request (`A4002`). Asked again with the row a write leaves: each row a
+     * create inserts (before the insert), and each row an update changed (after
+     * the write, inside its transaction; see `afterChecks`), one `afterChecks`
+     * lists with `before`, the same row as it was before the update; `false`
+     * refuses the write. An engine that requires one grant to cover a row both
+     * before and after its update lists the update and reads both, so no update
+     * moves a row from the rows one grant reaches to another's; one whose
+     * grants read relations through `exists` also answers {@link grantsOf}, so
+     * `before` is decided before the write. Rules that need a fact the row does not
+     * carry ask it through `exists`, which core runs through the adapter,
+     * unscoped, inside the write's transaction when it has one, and answers
+     * with a boolean only.
+     */
+    can(question: PolicyQuestion & {
+        readonly action: "read" | "create" | "update" | "delete";
+        readonly row?: Readonly<Record<string, unknown>>;
+        /**
+         * On the after check of an update `afterChecks` lists only: the
+         * changed row as it was before the update, read by core inside the
+         * update's transaction, with the fields `row` carries (its identifier
+         * and every scalar field). A root update and a to-many nested `$update`
+         * are held to that row as read (its values of the fields offering
+         * `equals` ANDed into the write's selector), so a concurrent change
+         * makes the write miss instead of passing a check on a stale `before`;
+         * an upsert's update branch, a to-one nested `$update` and a linked
+         * row's update have no selector to hold, and a field the adapter
+         * offers no `equals` for is not compared. An update of several rows that cannot pair a changed
+         * row with its `before` is refused. Absent on every other question, an
+         * unlisted update's after check included.
+         */
+        readonly before?: Readonly<Record<string, unknown>>;
+        /**
+         * With `before`, when the engine answers {@link grantsOf}: its answer
+         * about `before`, asked before the write and handed back unchanged, so
+         * an engine can require the grant that covers `row` to be one of these
+         * rather than decide `before`'s relation conditions after the write.
+         * Absent wherever `before` is absent, and when the engine has no `grantsOf`.
+         * An engine that answers `grantsOf` and finds `before` here without
+         * `beforeGrants` must refuse (`false`), never fall back to deciding
+         * `before` after the write: core states it on every such question, so
+         * its absence is a path core did not ask on, and the fallback is the
+         * gap `grantsOf` closes.
+         */
+        readonly beforeGrants?: readonly string[];
+        readonly exists: (resource: string, where: AvPolicyWhere) => Promise<boolean>;
+    }): PolicyAnswer<boolean>;
+    /**
+     * The grants that cover `row`, the row an update `afterChecks` lists will change,
+     * as it is before the write: asked once per such row, inside the update's
+     * transaction, after core read the row and before any interceptor, hook or the
+     * write itself runs, so `exists` sees no row the request writes. It takes no lock:
+     * a related row another transaction changes between `exists` and the write is not
+     * held. Each entry is the engine's own key for a grant; core never reads them, and
+     * hands the list back as `beforeGrants` on the after check of the same row. Never
+     * asked about an update `afterChecks` does not list, so an engine whose
+     * `afterChecks` lists none is never asked it, and that is no startup error: an
+     * engine may carry it whatever its rules list. An answer that is not a list of
+     * strings is the server's defect (`A3000`).
+     */
+    grantsOf?(question: PolicyQuestion & {
+        readonly action: "update";
+        readonly row: Readonly<Record<string, unknown>>;
+        readonly exists: (resource: string, where: AvPolicyWhere) => Promise<boolean>;
+    }): PolicyAnswer<readonly string[]>;
+    /**
+     * Told once, when a Framework is built on this engine and its startup
+     * checks have passed: `held` lists the Resources a written reference is held
+     * to the read scope of, every Resource the Core Contract shows but those
+     * {@link unheld} lists. A write that
+     * sends a reference to a row of one of them is refused (`A4002`) unless the
+     * caller may read that row; a reference to any other Resource is not asked
+     * about. An engine may check its rules against it here, as a warning; what
+     * it answers is unchanged. The list is frozen. It may answer with a
+     * promise, which construction awaits; a throw or a rejection fails the
+     * Framework's construction.
+     */
+    hosted?(host: {
+        readonly held: readonly string[];
+    }): PolicyAnswer<void>;
+    /**
+     * The rows the principal may `action`: `true` every row, `false` none, or a
+     * condition core ANDs into the request at every level that reads the
+     * Resource (its `where`, an included relation's, a relation filter, a
+     * relation count).
+     */
+    scopeOf(question: PolicyQuestion & {
+        readonly action: "read" | "update" | "delete";
+    }): PolicyAnswer<boolean | AvPolicyWhere>;
+    /**
+     * The fields the principal may read or write. `always` lists the fields it
+     * may use on every row it can reach (`"all"`: every field that is not
+     * governed); `perRow` maps a field it may use only on some rows to the
+     * condition those rows meet. A field in neither is refused (`A4002`)
+     * wherever the request names it. A write question names the `action` the
+     * fields are written by, `"create"` or `"update"` (an upsert's branches
+     * each by their own), so a field may be locked on update and still written
+     * at create.
+     */
+    fieldsOf(question: PolicyQuestion & ({
+        readonly access: "read";
+        readonly action?: undefined;
+    } | {
+        readonly access: "write";
+        readonly action: "create" | "update";
+    })): PolicyAnswer<{
+        readonly always: "all" | readonly string[];
+        readonly perRow: {
+            readonly [field: string]: AvPolicyWhere | undefined;
+        };
+    }>;
+}
+export {};

package/dist/policy/policy-engine.js

@@ -0,0 +1 @@
+export {};

package/dist/policy/policy-named-rows.d.ts

@@ -0,0 +1,18 @@
+import { type PolicyCondition } from "./policy-condition.js";
+import type { AvPolicyWhere } from "./policy-engine.js";
+import type { PolicySession } from "./policy-session.js";
+/** The rows a write names, each with the scopes it must be within. */
+export declare class NamedRows {
+    private readonly named;
+    /** Selectors with no stable key: asked the old way, outside any scope. */
+    private readonly unkeyed;
+    get size(): number;
+    /** Notes `selector` (one row by an identifier) held to `scope`; `true` holds nothing. */
+    add(selector: AvPolicyWhere, scope: PolicyCondition): void;
+    /**
+     * Whether every named row of `resource` is there and within its scopes: one
+     * count (an `exists` instead where the Resource offers neither a count nor a
+     * list, and one more for a selector with no stable key).
+     */
+    within(session: PolicySession, resource: string): Promise<boolean>;
+}

package/dist/policy/policy-named-rows.js

@@ -0,0 +1,51 @@
+import { allOf, everyOf, noneOf, someOf, whereOf, } from "./policy-condition.js";
+function selectorKey(selector) {
+    try {
+        return JSON.stringify(Object.entries(selector).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0), (_key, value) => typeof value === "bigint" ? `#bigint(${value})` : value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export class NamedRows {
+    named = new Map();
+    unkeyed = [];
+    get size() {
+        return this.named.size + this.unkeyed.length;
+    }
+    add(selector, scope) {
+        if (scope === true) {
+            return;
+        }
+        const key = selectorKey(selector);
+        if (key === undefined) {
+            this.unkeyed.push(allOf(selector, noneOf(scope)));
+            return;
+        }
+        const entry = this.named.get(key);
+        if (entry === undefined) {
+            this.named.set(key, { selector, scopes: [scope] });
+        }
+        else {
+            entry.scopes.push(scope);
+        }
+    }
+    async within(session, resource) {
+        const entries = [...this.named.values()];
+        const inside = someOf(entries.map(({ selector, scopes }) => allOf(selector, everyOf(scopes))));
+        let outside = someOf(this.unkeyed);
+        if (entries.length > 0) {
+            const counted = inside === false ? 0 : await session.count(resource, whereOf(inside));
+            if (counted === undefined) {
+                outside = someOf([
+                    outside,
+                    ...entries.map(({ selector, scopes }) => allOf(selector, noneOf(everyOf(scopes)))),
+                ]);
+            }
+            else if (counted < entries.length) {
+                return false;
+            }
+        }
+        return (outside === false || !(await session.exists(resource, whereOf(outside))));
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvContractCore } from "../contracts/contract.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type PolicyCondition } from "./policy-condition.js";
+import { type PolicySession } from "./policy-session.js";
+type Row = Readonly<Record<string, unknown>>;
+/** The rows a level's records write: new rows, or rows a condition reaches before the write. */
+export type NestedParent = {
+    readonly kind: "new";
+} | {
+    readonly kind: "existing";
+    readonly reach: PolicyCondition;
+};
+/** The checks after the write: told the root rows it wrote, the refusal or `undefined`. */
+export type NestedWriteCheck = (rows: readonly Row[]) => Promise<AvOperationFailureResponse | undefined>;
+/**
+ * What a nested write needs: a refusal before it runs, or the root record the
+ * adapter runs (its to-many `$update` and `$delete` narrowed to the rows within
+ * their scopes) and the check after it.
+ */
+export type NestedWritePlan = {
+    readonly kind: "refused";
+    readonly response: AvOperationFailureResponse;
+} | {
+    readonly kind: "planned";
+    readonly record: Row;
+    readonly after: NestedWriteCheck;
+    /**
+     * Asked when the adapter call failed: the refusal when a row a to-one `$update`
+     * was held to no longer holds the values it was read with, otherwise `undefined`
+     * and the failure stands.
+     */
+    readonly failed: () => Promise<AvOperationFailureResponse | undefined>;
+};
+/** Whether `record` of `resource` writes a relation through a directive. */
+export declare function writesNested(core: AvContractCore, resource: string, record: unknown): boolean;
+/**
+ * The policy of the nested writes in one root record (see the module comment):
+ * the refusal before the call, or the checks after it. `created` says the root
+ * rows are created by this write, so they too are read as stored and asked
+ * `can({ action: "create", row })` after the call.
+ */
+export declare function planNestedWrites(session: PolicySession, core: AvContractCore, model: AvAdapterModel, resource: string, record: Row, parent: NestedParent): Promise<NestedWritePlan>;
+export {};