@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/dist/access.engine.d.ts

@@ -0,0 +1,155 @@
+import type { AccessWhere } from "./aventara-where.translator.js";
+import { type AccessBeaconPins, type AccessBeaconReader } from "./beacon/beacon.check.js";
+import type { AccessGuardrails, AccessGuardrailsJson } from "./guardrails/guardrails-contract.js";
+import type { AccessLock } from "./lock/lock-contract.js";
+import { type AccessCanQuestion, type AccessFields, type AccessFieldsQuestion, type AccessGrantsQuestion, type AccessRuleOutcome, type AccessScopeQuestion } from "./policies.decider.js";
+import type { AccessPolicies, AccessPoliciesJson } from "./policies-contract.js";
+import type { AccessLookup } from "./predicate.evaluator.js";
+import { type AuthTablesGuard } from "./resources/auth-tables.guard.js";
+/** The `govern` block, by Resource: the list form (each field for both) or a mode per field. */
+type GovernedShape = {
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
+};
+/** One Resource's fields governed for reading: its list, or its fields not `"write"`. */
+type ReadGoverned<G> = G extends readonly string[] ? G[number] : {
+    [F in keyof G]: G[F] extends "write" ? never : F;
+}[keyof G] & string;
+/** `explain`'s answer: the decision, each rule's part in it, and the `exists` lookups. */
+export type AccessExplanation = {
+    readonly allowed: boolean;
+    readonly grants: readonly {
+        readonly id: string;
+        readonly subject: string;
+        readonly outcome: AccessRuleOutcome;
+    }[];
+    readonly denies: readonly {
+        readonly id: string;
+        readonly outcome: AccessRuleOutcome;
+    }[];
+    readonly lookups: readonly AccessLookup[];
+};
+/** The engine `access.engine()` and `createAccessEngine(policies)` return. */
+export interface AccessEngine<Governed extends GovernedShape = GovernedShape> {
+    /**
+     * The fields governed for reading (`"read"`, `"both"` or the list form), by
+     * Resource: out of every default projection. A `"write"` field is read as any other
+     * field, so it is not here.
+     */
+    readonly governed: {
+        readonly [R in keyof Governed as [ReadGoverned<Governed[R]>] extends [never] ? never : R]: Governed[R] extends readonly string[] ? Governed[R] : readonly ReadGoverned<Governed[R]>[];
+    };
+    /** Every relation path and operator each rule filters on, by rule id. */
+    readonly paths: {
+        readonly [rule: string]: readonly (readonly string[])[];
+    };
+    /**
+     * The Resources where the row an update leaves is checked: an update grant there
+     * reads the row (`where`, `after`, a role held on a row), or an update deny has a
+     * `where`.
+     */
+    readonly afterChecks: {
+        readonly [resource: string]: readonly "update"[];
+    };
+    /**
+     * The Resources the rules read as foreign: read in conditions, never granted on,
+     * so no caller reads a row of one. Aventara (`@aventara/core` `1.0.0-rc.10` or
+     * later) then holds no written reference to one to the caller's read scope: the
+     * write grant decides which row may be linked (its `where`, its `after`).
+     */
+    readonly unheld: readonly string[];
+    can(question: AccessCanQuestion): boolean | Promise<boolean>;
+    /**
+     * The update grants that cover `row`, the row an update in `afterChecks` will
+     * change, as it is before the write: each grant's `where` and its subject's row
+     * condition, relation conditions asked through `exists`. Core asks it before the
+     * write and hands the answer back to `can` as `beforeGrants` (`@aventara/core`
+     * `1.0.0-rc.10` or later). The keys are opaque: a grant's place in the file, no
+     * rule data.
+     */
+    grantsOf(question: AccessGrantsQuestion): readonly string[] | Promise<readonly string[]>;
+    scopeOf(question: AccessScopeQuestion): boolean | AccessWhere;
+    fieldsOf(question: AccessFieldsQuestion): AccessFields;
+    /**
+     * Called by the framework once it is built on this engine (`@aventara/core`
+     * `1.0.0-rc.10` or later): `held` lists the Resources a written reference is
+     * held to the caller's read scope of. The rules are checked against them, and a
+     * role that may write a reference to one no read grant reaches for it is warned
+     * about (ACCESS_REFERENCE_UNREADABLE), and so is a role whose create or update
+     * grant may write a reference to a foreign Resource with no condition through
+     * that relation (ACCESS_FOREIGN_REFERENCE_UNCHECKED), each once per process and
+     * namespace. It changes nothing the engine answers.
+     */
+    hosted(host: {
+        readonly held: readonly string[];
+    }): void;
+    /** Development only: why `can` answers as it does. Throws when `NODE_ENV` is `production`. */
+    explain(question: AccessCanQuestion): Promise<AccessExplanation>;
+    /**
+     * The startup check that the service reaches the database of each namespace
+     * whose Resources the rules read as foreign: its row in `_aventara_beacon`, read
+     * through `reader` (the service's own connection), hashes to its pin in `pins`,
+     * the pins of `environment` (`avAccess.beacons.<environment>.json`). Await it
+     * before the service takes requests: an engine whose rules read another
+     * namespace answers no question until it has passed, and none once a check has
+     * failed, for good (`ACCESS_BEACON_MISMATCH`); calls run one after another. An
+     * engine that reads no other namespace passes at once.
+     */
+    checkBeacons(reader: AccessBeaconReader, pins: AccessBeaconPins, environment: string): Promise<void>;
+}
+/** What an engine is built with beside its policies file. */
+export type AccessEngineOptions = {
+    /**
+     * The org's guardrails, as pulled from the registry: deny-only rules on top of the
+     * file's own. They only narrow; the governed fields, the paths and the types are
+     * the file's.
+     */
+    readonly guardrails?: AccessGuardrails | AccessGuardrailsJson;
+    /**
+     * The project's `avAccess.lock.json`, as `avaccess pull` wrote it. With it, the
+     * engine refuses to start (`ACCESS_LOCK_MISMATCH`) unless what it runs from is
+     * what was pulled: the guardrails hash to the lock's pin (and are given exactly
+     * when it pins some), and a policies file handed to `createAccessEngine` hashes
+     * to its own. Typed rules (`rules.engine()`) are the project's own source: only
+     * their namespace is held to the lock's, unless `requireLock` is set.
+     */
+    readonly lock?: AccessLock;
+    /**
+     * `true`: refuse to build without `lock` (`ACCESS_LOCK_MISMATCH`), so a deploy that
+     * lost its `avAccess.lock.json` fails at startup instead of running unpinned files;
+     * typed rules are then held to the lock's policies hash too. Recommended in
+     * production.
+     */
+    readonly requireLock?: boolean;
+};
+/** Where an engine's policies file comes from: a file handed over, or the project's typed rules. */
+export type PoliciesSource = "file" | "rules";
+/**
+ * What decided one `can` question: the grant that allowed it, or the deny that
+ * refused it; `null` when it was refused because no grant matched.
+ */
+export type DecidingRule = {
+    readonly kind: "grant" | "deny";
+    readonly id: string;
+} | null;
+/**
+ * Told of every `can` answer, after it is known and before `can` returns it: the
+ * audit log's hook into the engine. `can` waits for what it returns.
+ */
+export type DecisionObserver = (question: AccessCanQuestion, allowed: boolean, rule: DecidingRule) => void | Promise<void>;
+/**
+ * Builds the engine from a policies file and, optionally, the org's guardrails. Both
+ * are checked first; a bad one throws, naming the rule. With `lock`, both are held
+ * to the hashes `avAccess.lock.json` pins (`ACCESS_LOCK_MISMATCH`).
+ */
+export declare const createAccessEngine: <Governed extends GovernedShape = GovernedShape>(policies: AccessPolicies<Governed> | AccessPoliciesJson<Governed>, options?: AccessEngineOptions) => AccessEngine<Governed>;
+/**
+ * The engine, from a policies file that came from `source`: with a `lock`, a file
+ * handed over is held to the lock's pin, and typed rules (the project's own
+ * source) to its namespace only. `createAccess` adds its built-in rules over Better
+ * Auth's tables (`guard`): their denies join the file's, and `fieldsOf` never lists a
+ * secret column or a field a write may not set.
+ */
+export declare const engineOf: <Governed extends GovernedShape = GovernedShape>(policies: AccessPolicies<Governed>, options: AccessEngineOptions | undefined, source: PoliciesSource, observe?: DecisionObserver, guard?: AuthTablesGuard) => AccessEngine<Governed>;
+export {};

package/dist/access.engine.js

@@ -0,0 +1,477 @@
+// The engine: a plain object that answers core's `AvPolicyEngine` questions by shape
+// (`can`, `grantsOf`, `scopeOf`, `fieldsOf`, the startup facts `governed`,
+// `paths`, `afterChecks`, `unheld` (the Resources the rules read as foreign), and
+// `hosted`, where the framework says which Resources it holds a written reference
+// to and the rules are checked against them, reference-reads.check.ts and
+// foreign-references.check.ts), run from a `@1` policies file alone. Default deny, any grant
+// allows, any deny wins, order never matters. Neither package imports the other.
+// The decisions themselves are `policies.decider.ts`'s; the engine adds the lock,
+// the guardrails, the decision observer, `explain`, the startup facts and, when it
+// runs from a lock and its rules read other namespaces' Resources as foreign, the
+// startup check that the service reaches their database (`checkBeacons`): until it
+// has passed, the engine decides nothing.
+import { AccessError } from "./access/access.error.js";
+import { operatorOf } from "./aventara-where.translator.js";
+import { beaconProblem, } from "./beacon/beacon.check.js";
+import { warnForeignReferences } from "./foreign-references.check.js";
+import { composeGuardrails } from "./guardrails/guardrails.composer.js";
+import { foreignOwnersOf, verifyLocked } from "./lock/lock.verifier.js";
+import { checkLock } from "./lock/lock-contract.js";
+import { checkPolicies, fail, isRecord } from "./policies.compiler.js";
+import { afterChecksOf, createDecider, fieldsQuestionProblem, grantsQuestionProblem, newTrace, } from "./policies.decider.js";
+import { warnReadGovernedUnique } from "./read-governed-unique.check.js";
+import { warnReferenceReads } from "./reference-reads.check.js";
+import { guardedFields, withBuiltInRules, } from "./resources/auth-tables.guard.js";
+import { governedFor, nullSafe, ownOf, } from "./scope.resolver.js";
+const ENGINE_OPTIONS = new Set(["guardrails", "lock", "requireLock"]);
+/**
+ * The engine's own copy of a file handed to it: what is checked and hashed is what
+ * runs, whatever the caller does to its object afterwards.
+ */
+const copyOf = (what, file) => {
+    try {
+        return structuredClone(file);
+    }
+    catch {
+        return fail(what, "is JSON data: it holds a value that cannot be copied");
+    }
+};
+/** Freezes a copied file all the way down, once it is checked. */
+const deepFreeze = (value) => {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const member of Object.values(value)) {
+            deepFreeze(member);
+        }
+    }
+    return value;
+};
+// ---------------------------------------------------------------------------
+// Startup facts
+// ---------------------------------------------------------------------------
+const pathCollector = (policies) => {
+    const collect = (predicate, prefix, into, roles = new Set()) => {
+        switch (predicate.op) {
+            case "and":
+            case "or":
+                for (const arg of predicate.args) {
+                    collect(arg, prefix, into, roles);
+                }
+                return;
+            case "not":
+                collect(predicate.arg, prefix, into, roles);
+                return;
+            case "cmp":
+                into.push([...prefix, predicate.field, operatorOf(predicate.cmp)]);
+                return;
+            case "rel":
+                collect(predicate.where, [...prefix, predicate.relation], into, roles);
+                return;
+            case "some":
+            case "every":
+            case "none":
+                collect(predicate.where, [...prefix, predicate.relation, predicate.op], into, roles);
+                return;
+            case "role": {
+                const role = ownOf(policies.roles, predicate.role);
+                if (role !== undefined && "on" in role && !roles.has(predicate.role)) {
+                    collect(role.where, prefix, into, new Set([...roles, predicate.role]));
+                }
+                return;
+            }
+            default:
+                return;
+        }
+    };
+    return collect;
+};
+/**
+ * A rule's condition as the null-safe rewrite reads it: roles followed, a `me` value
+ * stood in for by a string (never `null`: a missing one folds the comparison away).
+ * Nothing is folded, so every comparison stays to be counted.
+ */
+const resolvedOf = (policies, predicate, roles = new Set()) => {
+    switch (predicate.op) {
+        case "true":
+        case "false":
+            return { k: predicate.op };
+        case "and":
+        case "or":
+            return {
+                k: predicate.op,
+                args: predicate.args.map((arg) => resolvedOf(policies, arg, roles)),
+            };
+        case "not":
+            return { k: "not", arg: resolvedOf(policies, predicate.arg, roles) };
+        case "cmp": {
+            const literal = (operand) => operand !== null && typeof operand === "object"
+                ? ""
+                : operand;
+            return {
+                k: "cmp",
+                field: predicate.field,
+                cmp: predicate.cmp,
+                value: Array.isArray(predicate.value)
+                    ? predicate.value.map(literal)
+                    : literal(predicate.value),
+            };
+        }
+        case "rel":
+        case "some":
+        case "every":
+        case "none":
+            return {
+                k: predicate.op,
+                relation: predicate.relation,
+                target: predicate.target,
+                where: resolvedOf(policies, predicate.where, roles),
+            };
+        case "role": {
+            const role = ownOf(policies.roles, predicate.role);
+            return role !== undefined && "on" in role && !roles.has(predicate.role)
+                ? resolvedOf(policies, role.where, new Set([...roles, predicate.role]))
+                : { k: "false" };
+        }
+    }
+};
+/** The filter paths a condition the null-safe rewrite wrote uses. */
+const resolvedPaths = (node, prefix, into) => {
+    switch (node.k) {
+        case "true":
+        case "false":
+            return;
+        case "cmp":
+            into.push([...prefix, node.field, operatorOf(node.cmp)]);
+            return;
+        case "and":
+        case "all":
+        case "or":
+            for (const arg of node.args) {
+                resolvedPaths(arg, prefix, into);
+            }
+            return;
+        case "not":
+            resolvedPaths(node.arg, prefix, into);
+            return;
+        case "rel":
+            resolvedPaths(node.where, [...prefix, node.relation], into);
+            return;
+        case "some":
+        case "every":
+        case "none":
+            resolvedPaths(node.where, [...prefix, node.relation, node.k], into);
+    }
+};
+/**
+ * The paths the null-safe rewrite adds to a condition on `resource`, read as it is
+ * (a grant, an `exists` question) and, for a deny, negated too (its scope): the
+ * `IS NULL` guards (`equals`), a reference's `IS NULL`, `not` for a `notIn` left
+ * empty, and the `none` and `some` an `every` becomes.
+ */
+const nullSafePaths = (policies, resource, predicate, negated, into) => {
+    const node = resolvedOf(policies, predicate);
+    resolvedPaths(nullSafe(policies, resource, node), [resource], into);
+    if (negated) {
+        resolvedPaths(nullSafe(policies, resource, { k: "not", arg: node }), [resource], into);
+    }
+};
+/** The to-one steps at a created row's own level, roles followed: each is one `exists` on its target. */
+const createSteps = (policies, predicate, roles = new Set()) => {
+    switch (predicate.op) {
+        case "and":
+        case "or":
+            return predicate.args.flatMap((arg) => createSteps(policies, arg, roles));
+        case "not":
+            return createSteps(policies, predicate.arg, roles);
+        case "rel":
+            return [predicate];
+        case "role": {
+            const role = ownOf(policies.roles, predicate.role);
+            return role !== undefined && "on" in role && !roles.has(predicate.role)
+                ? createSteps(policies, role.where, new Set([...roles, predicate.role]))
+                : [];
+        }
+        default:
+            return [];
+    }
+};
+const subjectPredicate = (policies, grant, subject) => {
+    const role = ownOf(policies.roles, subject);
+    if (role === undefined || !("on" in role)) {
+        return undefined;
+    }
+    const held = { op: "role", role: subject };
+    return grant.in === undefined
+        ? held
+        : { op: "rel", relation: grant.in, target: role.on, where: held };
+};
+const pathsOf = (policies) => {
+    const collect = pathCollector(policies);
+    const paths = {};
+    const existsPaths = (resource, predicate, into) => {
+        for (const step of createSteps(policies, predicate)) {
+            const relation = ownOf(ownOf(policies.schema, resource)?.relations, step.relation);
+            for (const reference of relation?.references ?? []) {
+                into.push([step.target, reference, "equals"]);
+            }
+            collect(step.where, [step.target], into);
+            nullSafePaths(policies, step.target, step.where, false, into);
+        }
+    };
+    const keep = (rule, found) => {
+        const unique = new Map(found.map((path) => [JSON.stringify(path), path]));
+        if (unique.size > 0) {
+            paths[rule] = [...unique.values()];
+        }
+    };
+    for (const grant of policies.grants) {
+        if (grant.resource === "*") {
+            continue;
+        }
+        const found = [];
+        const parts = [
+            grant.where,
+            ...grant.subjects.map((subject) => subjectPredicate(policies, grant, subject)),
+        ].filter((part) => part !== undefined);
+        for (const part of parts) {
+            collect(part, [grant.resource], found);
+            nullSafePaths(policies, grant.resource, part, false, found);
+        }
+        if (grant.after !== undefined) {
+            collect(grant.after, [grant.resource], found);
+            nullSafePaths(policies, grant.resource, grant.after, false, found);
+            const identifier = ownOf(policies.schema, grant.resource)?.identifiers[0] ?? [];
+            for (const field of identifier) {
+                found.push([grant.resource, field, "equals"]);
+            }
+        }
+        if (grant.actions.includes("create")) {
+            for (const part of parts) {
+                existsPaths(grant.resource, part, found);
+            }
+        }
+        keep(grant.id, found);
+    }
+    for (const deny of policies.denies) {
+        if (deny.where === undefined) {
+            continue;
+        }
+        const found = [];
+        collect(deny.where, [deny.resource], found);
+        // A scope (read, update, delete) negates the deny; a create only asks it as it is.
+        const scoped = deny.actions === "*" ||
+            deny.actions.some((action) => action !== "create");
+        nullSafePaths(policies, deny.resource, deny.where, scoped, found);
+        if (deny.actions === "*" || deny.actions.includes("create")) {
+            existsPaths(deny.resource, deny.where, found);
+        }
+        keep(deny.id, found);
+    }
+    return paths;
+};
+// ---------------------------------------------------------------------------
+// Decisions
+// ---------------------------------------------------------------------------
+/** The rule a trace shows deciding: the first grant matched, or the first deny that counted (fail closed). */
+const decidingRule = (trace, allowed) => {
+    if (allowed) {
+        for (const [grant, outcome] of trace.grants) {
+            if (outcome === "matched") {
+                return { kind: "grant", id: grant.grant.id };
+            }
+        }
+        return null;
+    }
+    for (const [deny, outcome] of trace.denies) {
+        if (outcome === "matched" || outcome === "unknown") {
+            return { kind: "deny", id: deny.deny.id };
+        }
+    }
+    return null;
+};
+/** Refuses a `fieldsOf` question the types rule out but a caller can still send (the decider refuses it too). */
+const checkFieldsQuestion = (question) => {
+    const problem = fieldsQuestionProblem(question);
+    if (problem !== undefined) {
+        throw new AccessError("ACCESS_QUESTION_INVALID", problem);
+    }
+};
+/**
+ * Builds the engine from a policies file and, optionally, the org's guardrails. Both
+ * are checked first; a bad one throws, naming the rule. With `lock`, both are held
+ * to the hashes `avAccess.lock.json` pins (`ACCESS_LOCK_MISMATCH`).
+ */
+export const createAccessEngine = (policies, options) => engineOf(policies, options, "file");
+/**
+ * The engine, from a policies file that came from `source`: with a `lock`, a file
+ * handed over is held to the lock's pin, and typed rules (the project's own
+ * source) to its namespace only. `createAccess` adds its built-in rules over Better
+ * Auth's tables (`guard`): their denies join the file's, and `fieldsOf` never lists a
+ * secret column or a field a write may not set.
+ */
+export const engineOf = (policies, options, source, observe, guard) => {
+    // The engine's own copy, checked, held to the lock, then frozen: nothing the
+    // caller does to its objects afterwards reaches what the engine runs from.
+    const own = copyOf("policies", policies);
+    checkPolicies(own);
+    warnReadGovernedUnique(own);
+    if (options !== undefined &&
+        (!isRecord(options) ||
+            Object.keys(options).some((key) => !ENGINE_OPTIONS.has(key)) ||
+            (options.requireLock !== undefined &&
+                typeof options.requireLock !== "boolean"))) {
+        fail("engine", "the engine's options are `{ guardrails?, lock?, requireLock?: boolean }`");
+    }
+    // A guardrails file imported as JSON is typed by its outline only; it is checked
+    // here (`composeGuardrails`), as a typed one is.
+    const guardrails = options?.guardrails === undefined
+        ? undefined
+        : copyOf("guardrails", options.guardrails);
+    if (options?.lock === undefined) {
+        if (options?.requireLock === true) {
+            throw new AccessError("ACCESS_LOCK_MISMATCH", "`requireLock` is set and no `lock` was given: pass the project's avAccess.lock.json (`avaccess pull` writes it), so the engine runs only from the files it pins");
+        }
+    }
+    else {
+        verifyLocked(checkLock(options.lock, "engine"), {
+            namespace: own.namespace,
+            // Typed rules are the project's own source; with `requireLock` they are held to
+            // the lock's pin too, so a lock that pins other rules is refused.
+            ...(source === "file" || options.requireLock === true
+                ? { policies: own }
+                : {}),
+            guardrails,
+        });
+    }
+    // The namespaces the rules read as foreign, from the file's own markers: with a
+    // lock or without, they are read only once the beacons have passed.
+    const owners = foreignOwnersOf(own);
+    const guarded = guardrails === undefined ? own : composeGuardrails(own, guardrails);
+    const file = deepFreeze(guard === undefined ? guarded : withBuiltInRules(guarded, guard));
+    if (file !== own) {
+        checkPolicies(file, true);
+    }
+    deepFreeze(own);
+    const decider = createDecider(file);
+    // The beacons' state: `undefined` once they have passed (or when the rules read
+    // no other namespace), otherwise why the engine answers nothing yet.
+    let refusal = owners.length === 0
+        ? undefined
+        : `the rules read ${owners.map((owner) => `namespace "${owner}"'s`).join(" and ")} Resources as foreign, and the beacons were not checked: \`await access.policy.checkBeacons(beacon, beaconPins, environment)\` (\`engine.checkBeacons\` on an engine of your own) when the service starts, before it takes requests, with this environment's avAccess.beacons.<environment>.json`;
+    // A failed check latches: no later check opens the engine again.
+    let failed;
+    // The checks, one after another.
+    let checking = Promise.resolve();
+    const open = () => {
+        if (refusal !== undefined) {
+            throw new AccessError("ACCESS_BEACON_MISMATCH", refusal);
+        }
+    };
+    const fieldsOf = (question) => {
+        open();
+        checkFieldsQuestion(question);
+        return guard === undefined
+            ? decider.fieldsOf(question)
+            : guardedFields(guard, question, decider.fieldsOf(question), {
+                fields: ownOf(file.schema, question.resource)?.fields ?? [],
+                // What `"all"` stands for: every field reads do not govern.
+                governed: governedFor(file, question.resource, "read"),
+            });
+    };
+    // The seam's `governed`: the fields reads leave out. The built-in rules govern
+    // for writing only, so the file's own reads are the same.
+    const governed = deepFreeze(Object.fromEntries(Object.keys(file.govern).flatMap((resource) => {
+        const fields = governedFor(file, resource, "read");
+        return fields.length === 0 ? [] : [[resource, [...fields]]];
+    })));
+    return {
+        governed: governed,
+        paths: deepFreeze(pathsOf(file)),
+        afterChecks: deepFreeze(afterChecksOf(file)),
+        unheld: Object.freeze(Object.entries(own.schema)
+            .filter(([, facts]) => facts.foreign !== undefined)
+            .map(([resource]) => resource)),
+        can: observe === undefined
+            ? (question) => {
+                open();
+                return decider.can(question, newTrace());
+            }
+            : (question) => {
+                open();
+                const trace = newTrace();
+                const report = async (allowed) => {
+                    await observe(question, allowed, decidingRule(trace, allowed));
+                    return allowed;
+                };
+                const answer = decider.can(question, trace);
+                return typeof answer === "boolean"
+                    ? report(answer)
+                    : answer.then(report);
+            },
+        grantsOf: (question) => {
+            open();
+            const problem = grantsQuestionProblem(question);
+            if (problem !== undefined) {
+                throw new AccessError("ACCESS_QUESTION_INVALID", problem);
+            }
+            return decider.grantsOf(question);
+        },
+        scopeOf: (question) => {
+            open();
+            return decider.scopeOf(question);
+        },
+        fieldsOf,
+        hosted: (host) => {
+            const held = isRecord(host) ? host.held : undefined;
+            if (!Array.isArray(held) ||
+                !held.every((resource) => typeof resource === "string")) {
+                throw new AccessError("ACCESS_QUESTION_INVALID", "`hosted` takes `{ held }`, the list of Resource names the framework holds a written reference to");
+            }
+            const served = new Set(held);
+            warnReferenceReads(own, served, guard?.closed);
+            warnForeignReferences(own, served);
+        },
+        explain: async (question) => {
+            open();
+            if (globalThis.process
+                ?.env?.NODE_ENV === "production") {
+                throw new Error("Aventara Access: explain() is for development only");
+            }
+            const trace = newTrace();
+            const allowed = await decider.can(question, trace);
+            return {
+                allowed,
+                grants: [...trace.grants].map(([grant, outcome]) => ({
+                    id: grant.grant.id,
+                    subject: grant.subject,
+                    outcome,
+                })),
+                denies: [...trace.denies].map(([deny, outcome]) => ({
+                    id: deny.deny.id,
+                    outcome,
+                })),
+                lookups: trace.lookups,
+            };
+        },
+        checkBeacons: (reader, pins, environment) => {
+            const run = async () => {
+                if (owners.length === 0) {
+                    return;
+                }
+                if (failed !== undefined) {
+                    throw new AccessError("ACCESS_BEACON_MISMATCH", `a beacon check failed before, and the engine stays shut: ${failed}`);
+                }
+                const problem = await beaconProblem(own.namespace ?? "", owners, pins, environment, reader);
+                if (problem !== undefined) {
+                    failed = problem;
+                    refusal = problem;
+                    throw new AccessError("ACCESS_BEACON_MISMATCH", problem);
+                }
+                refusal = undefined;
+            };
+            const result = checking.then(run);
+            checking = result.catch(() => undefined);
+            return result;
+        },
+    };
+};