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

package/dist/policy/access-provider.registry.d.ts

@@ -0,0 +1,17 @@
+import type { AvAccessProvider } from "./access-provider.interface.js";
+/** Records the provider `framework` was configured with; called once, at construction. */
+export declare function recordAccessProvider(framework: object, access: AvAccessProvider | undefined): void;
+/** What a host reads of the provider a Framework was configured with. */
+type AccessProviderView = {
+    /** The provider's `state`, called on the provider. */
+    readonly state: AvAccessProvider["state"];
+    /** The provider's `client`, when it has one. */
+    readonly client: AvAccessProvider["client"];
+};
+/**
+ * The provider `framework` was configured with (`access`), as a view;
+ * `undefined` for a Framework without `access`, or a value that is no
+ * constructed Framework.
+ */
+export declare function accessProviderOf(framework: object): AccessProviderView | undefined;
+export {};

package/dist/policy/access-provider.registry.js

@@ -0,0 +1,15 @@
+const ACCESS_PROVIDERS = new WeakMap();
+export function recordAccessProvider(framework, access) {
+    if (access !== undefined) {
+        ACCESS_PROVIDERS.set(framework, access);
+    }
+}
+export function accessProviderOf(framework) {
+    const access = ACCESS_PROVIDERS.get(framework);
+    return access === undefined
+        ? undefined
+        : Object.freeze({
+            state: (input) => access.state(input),
+            client: access.client,
+        });
+}

package/dist/policy/access-question.d.ts

@@ -0,0 +1,20 @@
+import type { AvPolicyWhere } from "./policy-engine.js";
+/**
+ * One question to the policy, as a client asks it: may the signed-in principal
+ * run `action` on `resource`, or on the one row `where` names. The answer is
+ * what the real call would do before any data is sent, decided by the same
+ * engine on the server; a row the principal cannot reach answers `false`
+ * exactly as a missing one does. It only shapes the UI, and the real call is
+ * still checked.
+ *
+ * The answer is about the row and the action, not about what a page reads of
+ * the row: it is the call selecting the Resource's identifier only. A field the
+ * principal reads on some rows only is checked by the page's own call that
+ * selects it, so `true` here and a refusal of that call can both hold.
+ */
+export type AvAccessQuestion<R extends string = string, UniqueWhere = AvPolicyWhere> = {
+    readonly resource: R;
+    readonly action: "read" | "create" | "update" | "delete";
+    /** One row, by its unique where. Omitted: may the principal run `action` on `resource` at all. */
+    readonly where?: UniqueWhere;
+};

package/dist/policy/access-question.js

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

package/dist/policy/access-question.registry.d.ts

@@ -0,0 +1,5 @@
+import type { AccessQuestionsAnswerer } from "./access-question.runtime.js";
+/** Records `framework`'s `can` answerer; called once, at construction. */
+export declare function recordAccessQuestions(framework: object, answer: AccessQuestionsAnswerer): void;
+/** `framework`'s `can` answerer, or `undefined` for anything `createFramework` did not return. */
+export declare function accessQuestionsOf(framework: object): AccessQuestionsAnswerer | undefined;

package/dist/policy/access-question.registry.js

@@ -0,0 +1,19 @@
+import { coreBrandOf } from "../runtime/core-class.brand.js";
+const ANSWERERS = sharedAnswererRegistry();
+function sharedAnswererRegistry() {
+    const key = coreBrandOf("access-questions");
+    const holder = globalThis;
+    const existing = holder[key];
+    if (existing instanceof WeakMap) {
+        return existing;
+    }
+    const registry = new WeakMap();
+    Object.defineProperty(holder, key, { value: registry });
+    return registry;
+}
+export function recordAccessQuestions(framework, answer) {
+    ANSWERERS.set(framework, answer);
+}
+export function accessQuestionsOf(framework) {
+    return ANSWERERS.get(framework);
+}

package/dist/policy/access-question.runtime.d.ts

@@ -0,0 +1,36 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterOperationExecutor } from "../adapters/adapter-operation-executor.interface.js";
+import type { AvContracts } from "../compiler/contract.compiler.js";
+import type { ResolvedPolicyConfig } from "../config/config.resolver.js";
+import type { RemoteRequestOrigin } from "../config/config-layer.js";
+import { type AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
+import type { MisuseReporter } from "../runtime/misuse-reporter.js";
+import { type AvOperationResponse } from "../runtime/operation-response.js";
+import type { AvState } from "../runtime/request-state.js";
+/** A `can` request as core answers it: the body the protocol read, under the request's origin, id and state. */
+export type AccessQuestionsRequest = {
+    readonly origin: RemoteRequestOrigin;
+    readonly requestId: string;
+    /** The request's `ctx.$state` as its host seeded it; absent, `{}`. */
+    readonly state?: AvState;
+    /** The JSON object the request carried: `{ questions }`. */
+    readonly body: unknown;
+};
+/** Answers one `can` request: `A1000` with one boolean per question, or the refusal. */
+export type AccessQuestionsAnswerer = (request: AccessQuestionsRequest) => Promise<AvOperationResponse<readonly boolean[]>>;
+/** What answering reads off the Framework. */
+type AccessQuestionsDependencies = {
+    readonly contracts: AvContracts;
+    readonly policy: ResolvedPolicyConfig | undefined;
+    readonly adapter: AvAdapterOperationExecutor & {
+        readonly model: AvAdapterModel;
+    };
+    readonly diagnostics: AvDiagnosticsSink | undefined;
+    readonly misuse: MisuseReporter;
+};
+/**
+ * Builds the `can` answerer of one Framework. Total: every request resolves to
+ * an answer, and no throw of the engine or the adapter escapes it.
+ */
+export declare function createAccessQuestionAnswerer(dependencies: AccessQuestionsDependencies): AccessQuestionsAnswerer;
+export {};

package/dist/policy/access-question.runtime.js

@@ -0,0 +1,297 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
+import { lookupOwn, lookupResource } from "../contracts/contract-lookup.js";
+import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
+import { resourceUnavailableIssue, validateOperationArguments, } from "../operations/operation-validator-core.js";
+import { validationIssue, } from "../operations/validation-code.js";
+import { copyAtDoor, refuseCallerData } from "../runtime/caller-data.door.js";
+import { createReporter, } from "../runtime/diagnostics-reporter.js";
+import { ADAPTER_FAILURE_MESSAGE, deliberateRefusalCode, } from "../runtime/error-boundary.js";
+import { internalFailure, operationFailure, operationSuccess, } from "../runtime/operation-response.js";
+import { VALIDATION_OUTCOME_MESSAGES } from "../runtime/outcome-mapper.js";
+import { requestStateOf } from "../runtime/request-state.resolver.js";
+import { normalizeOperationScalarValues } from "../runtime/scalar-runtime.js";
+import { admitByPolicy } from "./policy-admission.js";
+import { allOf, everyOf, whereOf } from "./policy-condition.js";
+import { openRequestPolicy } from "./policy-request.js";
+import { fieldAccess, } from "./policy-session.js";
+const ACTIONS = ["read", "create", "update", "delete"];
+const BODY_KEYS = new Set(["questions"]);
+const QUESTION_KEYS = new Set([
+    "resource",
+    "action",
+    "where",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const LIMIT_CODES = new Set([
+    "V1013",
+    "V1014",
+    "V1015",
+    "V1021",
+]);
+function refusal(issues) {
+    const code = issues.some((issue) => issue.code === "V1005" && issue.path?.[2] === "resource")
+        ? "A2001"
+        : issues.some((issue) => LIMIT_CODES.has(issue.code))
+            ? "A2009"
+            : "A2004";
+    return operationFailure(code, {
+        message: VALIDATION_OUTCOME_MESSAGES[code],
+        issues,
+    });
+}
+function unknownKeyIssues(record, allowed, path) {
+    return Object.keys(record)
+        .filter((key) => !allowed.has(key))
+        .map((key) => validationIssue("V1001", [...path, key], `Property "${key}" is not valid here.`));
+}
+function checkQuestion(active, origin, question, index) {
+    const at = ["questions", index];
+    if (!isRecord(question)) {
+        return [validationIssue("V1001", at, "Each question must be an object.")];
+    }
+    const issues = unknownKeyIssues(question, QUESTION_KEYS, at);
+    const { resource, action } = question;
+    let knownResource;
+    if (resource === undefined) {
+        issues.push(validationIssue("V1000", [...at, "resource"], 'Required property "resource" is missing.'));
+    }
+    else if (typeof resource !== "string") {
+        issues.push(validationIssue("V1001", [...at, "resource"], "resource must be a string."));
+    }
+    else if (lookupResource(active, resource) === undefined) {
+        const unavailable = resourceUnavailableIssue(resource);
+        issues.push({ ...unavailable, path: [...at, "resource"] });
+    }
+    else {
+        knownResource = resource;
+    }
+    if (action === undefined) {
+        issues.push(validationIssue("V1000", [...at, "action"], 'Required property "action" is missing.'));
+    }
+    else if (typeof action !== "string") {
+        issues.push(validationIssue("V1001", [...at, "action"], "action must be a string."));
+    }
+    else if (!ACTIONS.includes(action)) {
+        issues.push(validationIssue("V1002", [...at, "action"], 'action must be one of "read", "create", "update" or "delete".'));
+    }
+    const where = !Object.hasOwn(question, "where")
+        ? undefined
+        : action === "create"
+            ? [
+                validationIssue("V1001", [...at, "where"], "A create question names no row: it takes no where."),
+            ]
+            : checkedWhere(active, origin, knownResource, question.where, at);
+    if (Array.isArray(where)) {
+        issues.push(...where);
+    }
+    if (issues.length > 0 || knownResource === undefined) {
+        return issues;
+    }
+    return {
+        resource: knownResource,
+        action: action,
+        ...(where === undefined ? {} : { where: where }),
+    };
+}
+function checkedWhere(active, origin, resource, where, at) {
+    if (resource === undefined) {
+        return [];
+    }
+    const request = {
+        resource,
+        family: "find",
+        variant: "unique",
+        arguments: { where },
+    };
+    const validation = validateOperationArguments(active, request);
+    const normalized = validation.ok
+        ? normalizeOperationScalarValues(active, {
+            ...request,
+            arguments: validation.arguments,
+        }, origin)
+        : validation;
+    if (!normalized.ok) {
+        return normalized.issues.map((issue) => ({
+            ...issue,
+            path: [...at, ...(issue.path ?? ["arguments", "where"]).slice(1)],
+        }));
+    }
+    return normalized.arguments.where;
+}
+function checkQuestions(active, origin, body) {
+    if (!isRecord(body)) {
+        return refusal([
+            validationIssue("V1001", [], "The request body must be an object."),
+        ]);
+    }
+    const shape = unknownKeyIssues(body, BODY_KEYS, []);
+    if (!Object.hasOwn(body, "questions")) {
+        shape.push(validationIssue("V1000", ["questions"], 'Required property "questions" is missing.'));
+    }
+    else if (!Array.isArray(body.questions)) {
+        shape.push(validationIssue("V1001", ["questions"], "questions must be an array."));
+    }
+    if (shape.length > 0) {
+        return refusal(shape);
+    }
+    const questions = body.questions;
+    const limit = active.limits.maxListLimit;
+    if (questions.length > limit) {
+        return refusal([
+            validationIssue("V1014", ["questions"], `Question count exceeds maxListLimit (${limit}).`),
+        ]);
+    }
+    const checked = [];
+    const issues = [];
+    questions.forEach((question, index) => {
+        const result = checkQuestion(active, origin, question, index);
+        if (Array.isArray(result)) {
+            issues.push(...result);
+        }
+        else {
+            checked.push(result);
+        }
+    });
+    return issues.length > 0 ? refusal(issues) : checked;
+}
+function familyOf(action) {
+    return action === "read" ? "find" : action;
+}
+function advertised(active, question) {
+    const operations = lookupOwn(lookupResource(active, question.resource)?.operations, familyOf(question.action));
+    if (operations === undefined) {
+        return false;
+    }
+    return question.where === undefined
+        ? Object.keys(operations).some((variant) => isOperationVariantAvailable(lookupOwn(operations, variant)))
+        : isOperationVariantAvailable(lookupOwn(operations, "unique"));
+}
+async function answerQuestion(session, dependencies, active, question) {
+    if (!advertised(active, question)) {
+        return false;
+    }
+    const { resource, action, where } = question;
+    const identifier = adapterPrimaryIdentifier(dependencies.adapter.model, resource);
+    const interactive = active.transactions === "interactive";
+    if (action === "update") {
+        const checkedAfter = session.checksAfter(resource, "update");
+        if ((!interactive && checkedAfter) ||
+            ((interactive || checkedAfter) && identifier.length === 0)) {
+            return false;
+        }
+    }
+    if (where === undefined) {
+        return session.can(resource, action);
+    }
+    if (action === "create") {
+        return false;
+    }
+    const { core } = dependencies.contracts;
+    const refused = await admitByPolicy(session, core, active, {
+        resource,
+        family: action === "read" ? "find" : action,
+        variant: "unique",
+    }, { where, select: [...identifier] });
+    if (refused !== undefined) {
+        return false;
+    }
+    const read = await session.scope(resource, "read");
+    const scope = action === "read"
+        ? read
+        : allOf(await session.scope(resource, action), read);
+    const fields = await session.fields(resource, { access: "read" });
+    const grants = identifier.flatMap((field) => {
+        const access = fieldAccess(core, resource, fields, field);
+        return typeof access === "object" ? [access] : [];
+    });
+    if (action === "update" && !interactive && grants.length > 0) {
+        return false;
+    }
+    const reach = everyOf([where, scope, ...grants]);
+    return reach !== false && session.exists(resource, whereOf(reach));
+}
+const CONCURRENT_QUESTIONS = 8;
+async function answerAll(session, dependencies, active, questions) {
+    const settled = new Array(questions.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < questions.length) {
+            const index = next;
+            next += 1;
+            try {
+                settled[index] = {
+                    status: "fulfilled",
+                    value: await answerQuestion(session, dependencies, active, questions[index]),
+                };
+            }
+            catch (reason) {
+                settled[index] = { status: "rejected", reason };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENT_QUESTIONS, questions.length) }, worker));
+    return settled;
+}
+function isDeliberateRefusal(error) {
+    return deliberateRefusalCode(error) !== undefined;
+}
+function defectAnswer(dependencies, request, error, fromAdapter, blamed) {
+    createReporter(dependencies.diagnostics, {
+        kind: "can",
+        origin: "client",
+        requestId: request.requestId,
+        ...(blamed === undefined
+            ? {}
+            : {
+                question: blamed.index,
+                resource: blamed.question.resource,
+                action: blamed.question.action,
+            }),
+    })(error, fromAdapter ? "A3001" : "A3000");
+    return fromAdapter
+        ? operationFailure("A3001", { message: ADAPTER_FAILURE_MESSAGE })
+        : internalFailure();
+}
+export function createAccessQuestionAnswerer(dependencies) {
+    return async (request) => {
+        const active = dependencies.contracts[request.origin];
+        const copy = copyAtDoor(request.body);
+        if (!copy.ok) {
+            return refusal([
+                refuseCallerData(copy.error, [], { origin: request.origin }, dependencies.misuse),
+            ]);
+        }
+        const questions = checkQuestions(active, request.origin, copy.value);
+        if (!Array.isArray(questions)) {
+            return questions;
+        }
+        if (questions.length === 0) {
+            return operationSuccess([], "A1000");
+        }
+        let session;
+        try {
+            session = await openRequestPolicy(dependencies.policy, dependencies.contracts.core, { origin: request.origin, state: requestStateOf(request.state) }, undefined, dependencies.adapter);
+            if (session === undefined) {
+                throw new Error("The can route was reached on a Framework whose policy does not check its origin.");
+            }
+        }
+        catch (error) {
+            return defectAnswer(dependencies, request, error, false);
+        }
+        const settled = await answerAll(session, dependencies, active, questions);
+        const answers = [];
+        for (const [index, result] of settled.entries()) {
+            if (result.status === "rejected" && isDeliberateRefusal(result.reason)) {
+                answers.push(false);
+                continue;
+            }
+            if (result.status === "rejected") {
+                return defectAnswer(dependencies, request, result.reason, session.execution.boundary.originOf(result.reason) === "adapter", { question: questions[index], index });
+            }
+            answers.push(result.value);
+        }
+        return operationSuccess(answers, "A1000");
+    };
+}

package/dist/policy/access-verb.table.d.ts

@@ -0,0 +1,56 @@
+/** Each `$access` verb beside `can`, in `$access`'s order: whether it takes arguments, and what it resolves. */
+export declare const ACCESS_VERBS: Readonly<{
+    readonly me: {
+        readonly args: false;
+        readonly resolves: "identity";
+    };
+    readonly signIn: {
+        readonly args: true;
+        readonly resolves: "answer";
+    };
+    readonly signUp: {
+        readonly args: true;
+        readonly resolves: "answer";
+    };
+    readonly signOut: {
+        readonly args: false;
+        readonly resolves: "nothing";
+    };
+    readonly resetPassword: {
+        readonly args: true;
+        readonly resolves: "nothing";
+    };
+    readonly switchUser: {
+        readonly args: true;
+        readonly resolves: "answer";
+    };
+    readonly lock: {
+        readonly args: false;
+        readonly resolves: "nothing";
+    };
+    readonly setPin: {
+        readonly args: true;
+        readonly resolves: "nothing";
+    };
+    readonly enrollDevice: {
+        readonly args: true;
+        readonly resolves: "answer";
+    };
+    readonly revokeDevice: {
+        readonly args: true;
+        readonly resolves: "nothing";
+    };
+}>;
+/** One verb's row of {@link ACCESS_VERBS}. */
+export type AccessVerbShape = {
+    readonly args: boolean;
+    readonly resolves: "identity" | "answer" | "nothing";
+};
+/** A verb `$access` offers beside `can`. */
+export type AccessVerbName = keyof typeof ACCESS_VERBS;
+/** The verbs of {@link ACCESS_VERBS}, in `$access`'s order. */
+export declare const ACCESS_VERB_NAMES: readonly AccessVerbName[];
+/** The provider's `name` verb: its `verbs`' own enumerable member, else `undefined`. */
+export declare function providerVerb<Verbs extends object, Name extends string>(verbs: Verbs, name: Name): (Name extends keyof Verbs ? Verbs[Name] : unknown) | undefined;
+/** Whether `name` is one of `$access`'s verbs (an own key of the table, never `toString`). */
+export declare function isAccessVerbName(name: string): name is AccessVerbName;

package/dist/policy/access-verb.table.js

@@ -0,0 +1,21 @@
+export const ACCESS_VERBS = Object.freeze({
+    me: { args: false, resolves: "identity" },
+    signIn: { args: true, resolves: "answer" },
+    signUp: { args: true, resolves: "answer" },
+    signOut: { args: false, resolves: "nothing" },
+    resetPassword: { args: true, resolves: "nothing" },
+    switchUser: { args: true, resolves: "answer" },
+    lock: { args: false, resolves: "nothing" },
+    setPin: { args: true, resolves: "nothing" },
+    enrollDevice: { args: true, resolves: "answer" },
+    revokeDevice: { args: true, resolves: "nothing" },
+});
+export const ACCESS_VERB_NAMES = Object.freeze(Object.keys(ACCESS_VERBS));
+export function providerVerb(verbs, name) {
+    return Object.prototype.propertyIsEnumerable.call(verbs, name)
+        ? verbs[name]
+        : undefined;
+}
+export function isAccessVerbName(name) {
+    return Object.hasOwn(ACCESS_VERBS, name);
+}

package/dist/policy/access-verbs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `$access`: the policy's answers for the UI (`can`), and the Aventara Access
+ * verbs (`me`, `signIn`, `signUp`, `signOut`, `resetPassword`, and the `kiosk`
+ * profile's `switchUser`, `lock`, `setPin`, `enrollDevice`, `revokeDevice`).
+ */
+export type AvAccessVerbs<Question, Me, Args extends {
+    readonly signIn: unknown;
+    readonly signUp: unknown;
+    readonly resetPassword: unknown;
+    readonly switchUser: unknown;
+    readonly setPin: unknown;
+    readonly enrollDevice: unknown;
+    readonly revokeDevice: unknown;
+}, Options> = {
+    /**
+     * Asks the policy every question at once, in one request, and answers one
+     * boolean each, in order: what each call would do before any data is sent.
+     * It only shapes the UI; the real call is still checked.
+     */
+    can<const Q extends readonly Question[]>(questions: Q, options?: Options): Promise<{
+        readonly [K in keyof Q]: boolean;
+    }>;
+    /** Who is signed in: the token identity, or `null` when no one is. */
+    me(options?: Options): Promise<Me | null>;
+    /** Signs in through Aventara Access; resolves what Access answers. */
+    signIn(args: Args["signIn"], options?: Options): Promise<unknown>;
+    /** Signs up through Aventara Access; resolves what Access answers. */
+    signUp(args: Args["signUp"], options?: Options): Promise<unknown>;
+    /** Signs the caller out through Aventara Access. */
+    signOut(options?: Options): Promise<void>;
+    /** Resets a password through Aventara Access. */
+    resetPassword(args: Args["resetPassword"], options?: Options): Promise<void>;
+    /**
+     * Switches this enrolled device to another staff member by their PIN
+     * (Aventara Access, `kiosk` profile); resolves what Access answers.
+     */
+    switchUser(args: Args["switchUser"], options?: Options): Promise<unknown>;
+    /** Locks this enrolled device: ends its session, keeps it enrolled (`kiosk` profile). */
+    lock(options?: Options): Promise<void>;
+    /** Sets the signed-in staff member's PIN (`kiosk` profile). */
+    setPin(args: Args["setPin"], options?: Options): Promise<void>;
+    /** Enrolls this device for PIN switching (`kiosk` profile); resolves what Access answers. */
+    enrollDevice(args: Args["enrollDevice"], options?: Options): Promise<unknown>;
+    /** Revokes an enrolled device (`kiosk` profile). */
+    revokeDevice(args: Args["revokeDevice"], options?: Options): Promise<void>;
+};

package/dist/policy/access-verbs.js

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

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

@@ -0,0 +1,20 @@
+import type { AvContract, AvContractCore } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type PolicySession } from "./policy-session.js";
+/** The refusal every policy decision answers: `A4002`. */
+export declare function policyRefusal(message: string): AvOperationFailureResponse;
+/**
+ * Policy admission for one request (see the module comment): the refusal, or
+ * `undefined` when the request may go on to its guards.
+ */
+export declare function admitByPolicy(session: PolicySession, core: AvContractCore, active: AvContract, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown): Promise<AvOperationFailureResponse | undefined>;
+/**
+ * The write half of policy admission: every field the write sends against
+ * `fieldsOf(write)`, nested records included, the refusal or `undefined`.
+ */
+export declare function admitWriteByPolicy(session: PolicySession, core: AvContractCore, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown): Promise<AvOperationFailureResponse | undefined>;