@aventara/access 0.0.0-stage → 0.1.0-rc.0

package/dist/access-schema.d.ts

@@ -0,0 +1,48 @@
+/** A scalar field as discovery states it. */
+export type AccessSchemaScalarField = {
+    readonly kind: "scalar";
+    readonly type: {
+        readonly scalar: string;
+    } | {
+        readonly enum: string;
+    };
+    readonly nullable: boolean;
+    readonly list: boolean;
+};
+/** A relation field as discovery states it, with the `references` it holds. */
+export type AccessSchemaRelationField = {
+    readonly kind: "relation";
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+    readonly nullable: boolean;
+    readonly inverse?: string;
+    readonly referenceFields?: readonly [string, ...string[]];
+    readonly references?: readonly [string, ...string[]];
+};
+/** One field of a Resource. */
+export type AccessSchemaField = AccessSchemaScalarField | AccessSchemaRelationField;
+/** One Resource: its fields and the field tuples that identify a row. */
+export type AccessSchemaResource = {
+    readonly fields: {
+        readonly [field: string]: AccessSchemaField;
+    };
+    readonly identifiers: readonly (readonly string[])[];
+    /**
+     * The namespace that owns this Resource, when another one does (`{ foreign: "campaign" }`).
+     * Rules read a foreign Resource in conditions and never grant on it.
+     */
+    readonly foreign?: string;
+};
+/** The schema facts Access reads: the enums and the Resources. */
+export type AccessSchema = {
+    readonly enums: {
+        readonly [name: string]: {
+            readonly values: readonly string[];
+        };
+    };
+    readonly resources: {
+        readonly [resource: string]: AccessSchemaResource;
+    };
+};
+/** The TypeScript value a built-in scalar compares with. Unknown scalars compare with `unknown`. */
+export type AccessScalarValue<Scalar extends string> = Scalar extends "string" ? string : Scalar extends "boolean" ? boolean : Scalar extends "int" | "float" ? number : Scalar extends "bigint" ? bigint : Scalar extends "decimal" ? number | string : Scalar extends "datetime" ? Date | string : unknown;

package/dist/access-schema.js

@@ -0,0 +1,5 @@
+// The schema shape Access is typed from and compiles against. It is a structural
+// subset of core's `AvAdapterModel` (a Prisma discovery artifact's `model`), so an
+// Aventara app passes its discovery model in and Access imports nothing from core.
+// The type test `test/core-seam.test-d.ts` holds the two together.
+export {};

package/dist/access-warning.emitter.d.ts

@@ -0,0 +1,2 @@
+/** Emits `message` under `code`, once per process and `namespace`. */
+export declare const emitAccessWarning: (code: string, namespace: string | undefined, message: string) => void;

package/dist/access-warning.emitter.js

@@ -0,0 +1,20 @@
+// How the engine's checks against a hosting framework warn: Node.js's
+// `process.emitWarning` (type `AventaraAccessWarning`, the check's code, silenced
+// with `--disable-warning=<code>`), else `console.warn`. Each message is emitted
+// once per process and namespace, however many Frameworks host the rules.
+const emitted = new Set();
+/** Emits `message` under `code`, once per process and `namespace`. */
+export const emitAccessWarning = (code, namespace, message) => {
+    const key = `${code}\u0000${namespace ?? ""}\u0000${message}`;
+    if (emitted.has(key)) {
+        return;
+    }
+    emitted.add(key);
+    const runtime = globalThis.process;
+    if (typeof runtime?.emitWarning === "function") {
+        runtime.emitWarning(message, { type: "AventaraAccessWarning", code });
+    }
+    else {
+        globalThis.console?.warn(`${code}: ${message}`);
+    }
+};

package/dist/access.builder.d.ts

@@ -0,0 +1,299 @@
+import { type AccessEngine, type AccessEngineOptions } from "./access.engine.js";
+import type { AccessScalarValue, AccessSchema } from "./access-schema.js";
+import type { AccessAction, AccessBuiltInSubject, AccessOrigin, AccessPolicies } from "./policies-contract.js";
+declare const principalRefBrand: unique symbol;
+/**
+ * A value read off the principal when a question is asked (`me.id`). `T` is the
+ * value's type, so `me.id` compares only with a field of that type.
+ */
+export type AccessPrincipalRef<T = unknown> = {
+    readonly [principalRefBrand]: T;
+    readonly path: readonly [string, ...string[]];
+};
+/**
+ * The principal, symbolically, typed from `.principal<P>()`: one key per key of
+ * `P`, so `me.profleId` is a tsc error. `me.id` is a token the compiler writes
+ * into the file as `{ principal: ["id"] }`, never a value. A rule about `me` is
+ * false for an anonymous (null) principal, and for one that lacks the value.
+ */
+export type AccessMe<P> = {
+    readonly [K in Extract<keyof NonNullable<P>, string>]-?: AccessPrincipalRef<NonNullable<NonNullable<P>[K]>>;
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type GovernedShape = {
+    readonly [resource: string]: readonly string[];
+};
+/** A row role as the builder's type records it: the Resource it is held on. */
+type RoleShape = {
+    readonly on: string;
+} | {
+    readonly global: unknown;
+};
+/** The roles in scope inside a role's own `where`: any name (the compiler checks them). */
+type AnyRoles = {
+    readonly [role: string]: {
+        readonly on: string;
+    };
+};
+type ResourceOf<S extends AccessSchema> = Extract<keyof S["resources"], string>;
+/**
+ * The file's own Resources: all but the foreign ones (`{ foreign: "<namespace>" }`).
+ * Grants, denies and governed fields name only these; a foreign Resource is read in
+ * conditions alone.
+ */
+type OwnResourceOf<S extends AccessSchema> = {
+    [R in ResourceOf<S>]: S["resources"][R] extends {
+        readonly foreign: string;
+    } ? never : R;
+}[ResourceOf<S>];
+type FieldMap<S extends AccessSchema, R extends ResourceOf<S>> = S["resources"][R]["fields"];
+/** A Resource's field names. */
+export type AccessFieldOf<S extends AccessSchema, R extends ResourceOf<S>> = Extract<keyof FieldMap<S, R>, string>;
+type NullIf<F> = F extends {
+    readonly nullable: true;
+} ? null : never;
+/** The literal a scalar field compares with: its enum's values, or its scalar's TS type. */
+type ScalarValue<S extends AccessSchema, F> = F extends {
+    readonly list: true;
+} ? never : F extends {
+    readonly type: {
+        readonly enum: infer E extends keyof S["enums"];
+    };
+} ? S["enums"][E]["values"][number] | NullIf<F> : F extends {
+    readonly type: {
+        readonly scalar: infer T extends string;
+    };
+} ? AccessScalarValue<T> | NullIf<F> : never;
+type Operand<V> = V | AccessPrincipalRef<V>;
+type ScalarCondition<V> = Operand<V> | {
+    readonly equals?: Operand<V>;
+    readonly not?: Operand<V>;
+    readonly in?: readonly Operand<V>[];
+    readonly notIn?: readonly Operand<V>[];
+};
+type RelationCondition<S extends AccessSchema, F, Roles> = F extends {
+    readonly cardinality: "one";
+    readonly target: infer T extends ResourceOf<S>;
+} ? AccessWhereInput<S, T, Roles> : F extends {
+    readonly cardinality: "many";
+    readonly target: infer T extends ResourceOf<S>;
+} ? {
+    readonly some?: AccessWhereInput<S, T, Roles>;
+    readonly every?: AccessWhereInput<S, T, Roles>;
+    readonly none?: AccessWhereInput<S, T, Roles>;
+} : never;
+type FieldCondition<S extends AccessSchema, F, Roles> = F extends {
+    readonly kind: "relation";
+} ? RelationCondition<S, F, Roles> : ScalarCondition<ScalarValue<S, F>>;
+/** The row roles held on Resource `R`. */
+type RoleOn<Roles, R extends string> = string extends keyof Roles ? string : {
+    [K in keyof Roles]: Roles[K] extends {
+        readonly on: R;
+    } ? K : never;
+}[keyof Roles] & string;
+/**
+ * A row condition on Resource `R`, in Aventara's `where` vocabulary: fields by
+ * name (a value is `equals`), `AND` / `OR` / `NOT`, a to-one relation by direct
+ * match, a to-many by `some` / `every` / `none`, and `$role`, a row role held on
+ * `R`.
+ */
+export type AccessWhereInput<S extends AccessSchema, R extends ResourceOf<S>, Roles> = {
+    readonly [F in AccessFieldOf<S, R>]?: FieldCondition<S, FieldMap<S, R>[F], Roles>;
+} & {
+    readonly AND?: readonly AccessWhereInput<S, R, Roles>[];
+    readonly OR?: readonly AccessWhereInput<S, R, Roles>[];
+    readonly NOT?: AccessWhereInput<S, R, Roles>;
+    readonly $role?: RoleOn<Roles, R>;
+};
+type ClaimsOf<P> = P extends {
+    readonly claims?: infer C;
+} ? NonNullable<C> : never;
+/** A condition on the principal's claims: each named claim equals the value. */
+export type AccessClaimsCondition<P> = [ClaimsOf<P>] extends [never] ? never : {
+    readonly [K in keyof ClaimsOf<P>]?: Exclude<ClaimsOf<P>[K], undefined>;
+};
+type RowRoleDefinition<S extends AccessSchema> = {
+    [R in ResourceOf<S>]: {
+        readonly on: R;
+        readonly where: AccessWhereInput<S, R, AnyRoles>;
+    };
+}[ResourceOf<S>];
+type GlobalRoleDefinition<P> = {
+    readonly global: {
+        readonly claims: AccessClaimsCondition<P>;
+    };
+};
+/** The `.roles({...})` argument: global roles from claims, row roles on one Resource. */
+export type AccessRoleDefinitions<S extends AccessSchema, P> = {
+    readonly [role: string]: GlobalRoleDefinition<P> | RowRoleDefinition<S>;
+};
+/** Each role of `D` checked against its own shape; built-in subject names refused. */
+type CheckedRoles<S extends AccessSchema, P, D> = {
+    readonly [K in keyof D]: K extends AccessBuiltInSubject ? never : D[K] extends {
+        readonly on: infer R extends ResourceOf<S>;
+        readonly where: infer W;
+    } ? {
+        readonly on: R;
+        readonly where: NoExtraKeys<W, AccessWhereInput<S, R, AnyRoles>, "a field, relation or operator">;
+    } : D[K] extends {
+        readonly global: {
+            readonly claims: infer C;
+        };
+    } ? {
+        readonly global: {
+            readonly claims: NoExtraKeys<C, AccessClaimsCondition<P>, "a claim of the principal">;
+        };
+    } : AccessRoleDefinitions<S, P>[string];
+};
+/** Every key of every object member of a union. */
+type KeysOfUnion<U> = U extends unknown ? keyof U : never;
+/** The type of key `K` across the object members of a union that have it. */
+type MemberOf<U, K> = U extends unknown ? K extends keyof U ? U[K] : never : never;
+/**
+ * `T` checked against `Shape`, at any depth: each key `Shape` does not have is
+ * typed as the sentence that says so, and each value as `Shape` allows it.
+ */
+type NoExtraKeys<T, Shape, Noun extends string> = T extends string | number | boolean | bigint | symbol | null | undefined | AccessPrincipalRef ? Shape : T extends readonly (infer E)[] ? Shape extends unknown ? readonly NoExtraKeys<E, NonNullable<Shape> extends readonly (infer SE)[] ? SE : never, Noun>[] : never : {
+    readonly [K in keyof T]: K extends KeysOfUnion<Exclude<Extract<NonNullable<Shape>, object>, AccessPrincipalRef>> ? NoExtraKeys<T[K], MemberOf<Exclude<Extract<NonNullable<Shape>, object>, AccessPrincipalRef>, K>, Noun> : `Error: "${K & string}" is not ${Noun} here`;
+};
+/** Who a grant is for: a built-in subject or a role. */
+type Subject<Roles> = AccessBuiltInSubject | Extract<keyof Roles, string>;
+type OneOrMany<T> = T | readonly [T, ...T[]];
+type Each<T> = T extends readonly (infer X)[] ? X : T;
+/** The Resource every subject's row role is held on; `never` when one subject is not a row role. */
+type SubjectsOn<Roles, Sub> = [Sub] extends [never] ? never : Sub extends keyof Roles ? Roles[Sub] extends {
+    readonly on: infer On extends string;
+} ? On : "~not-a-row-role" : "~not-a-row-role";
+/** The to-one relations of `R` that lead to `On`. */
+type InRelation<S extends AccessSchema, R extends ResourceOf<S>, On> = {
+    [F in AccessFieldOf<S, R>]: FieldMap<S, R>[F] extends {
+        readonly kind: "relation";
+        readonly cardinality: "one";
+        readonly target: infer T;
+    } ? T extends On ? F : never : never;
+}[AccessFieldOf<S, R>];
+type InOption<S extends AccessSchema, R, Roles, Sub> = R extends ResourceOf<S> ? "~not-a-row-role" extends SubjectsOn<Roles, Each<Sub>> ? never : InRelation<S, R, SubjectsOn<Roles, Each<Sub>>> : never;
+/**
+ * A governed field named `Resource.field`. On `"*"`, any Resource's governed fields.
+ * A Resource with no governed field has none to name: the type is the sentence that
+ * says to govern one first, so naming a field reads as what to change.
+ */
+type GovernedRef<Gov, R> = R extends "*" ? [keyof Gov] extends [never] ? "Error: no field is governed; govern one first, .govern(<Resource>, [<field>]), and a grant can then open it" : {
+    [K in keyof Gov]: `${K & string}.${Gov[K] extends readonly (infer F extends string)[] ? F : never}`;
+}[keyof Gov] : R extends keyof Gov ? `${R & string}.${Gov[R] extends readonly (infer F extends string)[] ? F : never}` : `Error: no field of "${R & string}" is governed; govern it first, .govern("${R & string}", [<field>]), and a grant can then open it`;
+type ResourceWhere<S extends AccessSchema, R, Roles> = R extends ResourceOf<S> ? AccessWhereInput<S, R, Roles> : never;
+/** The options of `grant(subjects, actions, resource, options)`. */
+export type AccessGrantOptions<S extends AccessSchema, Roles, Gov, R, Sub, A> = {
+    /** A name for the rule's id (else `Resource/actions/subjects#n`). */
+    readonly name?: string;
+    /** The rows the grant covers. */
+    readonly where?: ResourceWhere<S, R, Roles>;
+    /** `in: "campaign"`: each subject holds its row role on this row's `campaign`. */
+    readonly in?: InOption<S, R, Roles, Sub>;
+    /** Governed fields the grant opens, as `Resource.field`. */
+    readonly fields?: readonly GovernedRef<Gov, R>[];
+    /** Fields a create or update by this grant may not write. */
+    readonly write?: Extract<Each<A>, "create" | "update"> extends never ? never : R extends ResourceOf<S> ? {
+        readonly except: readonly AccessFieldOf<S, R>[];
+    } : never;
+    /** What the row an update leaves must still meet. */
+    readonly after?: "update" extends Each<A> ? ResourceWhere<S, R, Roles> : never;
+};
+/** The options of `deny(actions, resource, options)`. */
+export type AccessDenyOptions<S extends AccessSchema, P, Roles, R> = {
+    /** A name for the rule's id (else `Resource/actions/deny#n`). */
+    readonly name?: string;
+    /** The rows the deny covers. */
+    readonly where?: ResourceWhere<S, R, Roles>;
+    /** A condition on the principal alone: its claims and the request's origin. */
+    readonly if?: {
+        readonly claims?: AccessClaimsCondition<P>;
+        readonly origin?: AccessOrigin;
+    };
+};
+declare const grantBrand: unique symbol;
+declare const denyBrand: unique symbol;
+/** A grant, as data, before compilation. */
+export type AccessGrant = {
+    readonly [grantBrand]: true;
+    readonly subjects: OneOrMany<string>;
+    readonly actions: OneOrMany<AccessAction>;
+    readonly resource: string;
+    readonly options: {
+        readonly [option: string]: unknown;
+    };
+};
+/** A deny, as data, before compilation. */
+export type AccessDeny = {
+    readonly [denyBrand]: true;
+    readonly actions: "*" | OneOrMany<AccessAction>;
+    readonly resource: string;
+    readonly options: {
+        readonly [option: string]: unknown;
+    };
+};
+/** `grant(subjects, actions, resource, options?)`: any grant allows. */
+export type AccessGrantFunction<S extends AccessSchema, Roles, Gov> = <const Sub extends OneOrMany<Subject<Roles>>, const A extends OneOrMany<AccessAction>, const R extends OwnResourceOf<S> | "*">(subjects: Sub, actions: A, resource: R, options?: AccessGrantOptions<S, Roles, Gov, NoInfer<R>, NoInfer<Sub>, NoInfer<A>>) => AccessGrant;
+/** `deny(actions, resource, options?)`: any deny wins. */
+export type AccessDenyFunction<S extends AccessSchema, P, Roles> = <const A extends "*" | OneOrMany<AccessAction>, const R extends OwnResourceOf<S> | "*">(actions: A, resource: R, options?: AccessDenyOptions<S, P, Roles, NoInfer<R>>) => AccessDeny;
+/** The rules as written, before compilation. */
+export type AccessDefinition = {
+    readonly schema: AccessSchema;
+    readonly namespace?: string;
+    readonly roles: {
+        readonly [role: string]: unknown;
+    };
+    readonly govern: {
+        readonly [resource: string]: readonly string[];
+    };
+    readonly grants: readonly AccessGrant[];
+    readonly denies: readonly AccessDeny[];
+};
+/** The builder `definePolicies` returns. Each call returns a new builder; none has side effects. */
+export interface AccessBuilder<S extends AccessSchema, P, Roles extends {
+    readonly [role: string]: RoleShape;
+}, Gov extends GovernedShape> {
+    /** Types the principal. Anonymous is `null`; rules about `me` are false for it. */
+    principal<T>(): AccessBuilder<S, T, Roles, Gov>;
+    /** Global roles (`global: { claims }`) and roles held on a row (`on`, `where`). */
+    roles<const D extends {
+        readonly [role: string]: RoleShape;
+    }>(definitions: (tools: {
+        readonly me: AccessMe<P>;
+    }) => D extends CheckedRoles<S, P, D> ? D : CheckedRoles<S, P, D>): AccessBuilder<S, P, Simplify<Roles & D>, Gov>;
+    /** Governed fields: out of every default projection; only a grant that names one opens it, and only when selected. */
+    govern<R extends OwnResourceOf<S>, const F extends readonly [AccessFieldOf<S, R>, ...AccessFieldOf<S, R>[]]>(resource: R, fields: F): AccessBuilder<S, P, Roles, Simplify<Gov & {
+        readonly [K in R]: F;
+    }>>;
+    /** Grants. Default deny; any grant allows; order never matters. */
+    grants(rules: (tools: {
+        readonly grant: AccessGrantFunction<S, Roles, Gov>;
+        readonly me: AccessMe<P>;
+    }) => readonly AccessGrant[]): AccessBuilder<S, P, Roles, Gov>;
+    /** Denies. Any deny wins over every grant; order never matters. */
+    denies(rules: (tools: {
+        readonly deny: AccessDenyFunction<S, P, Roles>;
+        readonly me: AccessMe<P>;
+    }) => readonly AccessDeny[]): AccessBuilder<S, P, Roles, Gov>;
+    /** The compiled `@1` policies file. */
+    contract(): AccessPolicies<Gov>;
+    /**
+     * The engine, run from the compiled file and, with `guardrails`, the org's
+     * guardrails on top of it. With `lock`, the guardrails are held to the hash
+     * `avAccess.lock.json` pins, and the rules' namespace to its namespace.
+     * Satisfies core's `AvPolicyEngine` by shape.
+     */
+    engine(options?: AccessEngineOptions): AccessEngine<Gov>;
+}
+/**
+ * Starts the rules for an app, typed from its schema (an Aventara discovery
+ * artifact's `model`, or any object of the {@link AccessSchema} shape).
+ * `namespace` names the namespace that owns these Resources; it is written into
+ * the compiled file.
+ */
+export declare const definePolicies: <const S extends AccessSchema>(schema: S, options?: {
+    readonly namespace?: string;
+}) => AccessBuilder<S, unknown, Record<never, never>, Record<never, never>>;
+export {};

package/dist/access.builder.js

@@ -0,0 +1,66 @@
+// `definePolicies(model)`: the typed authoring API. It captures the author's
+// rules as plain data and compiles them to the `@1` policies file; the engine runs
+// from that file alone. Every name a rule uses (Resource, field,
+// relation, enum value, role, governed field) is checked at its key against the
+// schema the builder was created from.
+import { engineOf, } from "./access.engine.js";
+import { compilePolicies, PRINCIPAL_REF } from "./policies.compiler.js";
+/** The one runtime `me`: any key reads as a principal reference. */
+const me = new Proxy({}, {
+    get(_target, key) {
+        if (typeof key !== "string") {
+            return undefined;
+        }
+        return Object.freeze({
+            [PRINCIPAL_REF]: true,
+            path: Object.freeze([key]),
+        });
+    },
+});
+const grant = (subjects, actions, resource, options = {}) => Object.freeze({
+    subjects,
+    actions,
+    resource,
+    options,
+});
+const deny = (actions, resource, options = {}) => Object.freeze({ actions, resource, options });
+const builderOf = (definition) => ({
+    principal: () => builderOf(definition),
+    roles: (definitions) => builderOf({
+        ...definition,
+        roles: { ...definition.roles, ...definitions({ me }) },
+    }),
+    govern: (resource, fields) => builderOf({
+        ...definition,
+        govern: {
+            ...definition.govern,
+            [resource]: [...(definition.govern[resource] ?? []), ...fields],
+        },
+    }),
+    grants: (rules) => builderOf({
+        ...definition,
+        grants: [...definition.grants, ...rules({ grant, me })],
+    }),
+    denies: (rules) => builderOf({
+        ...definition,
+        denies: [...definition.denies, ...rules({ deny, me })],
+    }),
+    contract: () => compilePolicies(definition),
+    engine: (options) => engineOf(compilePolicies(definition), options, "rules"),
+});
+/**
+ * Starts the rules for an app, typed from its schema (an Aventara discovery
+ * artifact's `model`, or any object of the {@link AccessSchema} shape).
+ * `namespace` names the namespace that owns these Resources; it is written into
+ * the compiled file.
+ */
+export const definePolicies = (schema, options) => builderOf({
+    schema,
+    ...(options?.namespace !== undefined
+        ? { namespace: options.namespace }
+        : {}),
+    roles: {},
+    govern: {},
+    grants: [],
+    denies: [],
+});

package/dist/access.engine.d.ts

@@ -0,0 +1,142 @@
+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";
+type GovernedShape = {
+    readonly [resource: string]: readonly 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 governed fields, by Resource: out of every default projection. */
+    readonly governed: Governed;
+    /** 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 {};