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

package/dist/resources/auth-tables.guard.d.ts

@@ -0,0 +1,95 @@
+import type { AccessFields, AccessFieldsQuestion } from "../policies.decider.js";
+import type { AccessDenyRule, AccessPolicies } from "../policies-contract.js";
+import { type AuthResourceKey, type AuthTable, type AuthTableNaming } from "./auth-tables.catalog.js";
+/**
+ * The `resources` block: which of Better Auth's tables are Resources of the app's
+ * rules. Every other table of Better Auth's stays closed.
+ */
+export type AccessResourcesOptions = {
+    /**
+     * Better Auth's `user`, `session` and `account` tables: read as the rules grant,
+     * secret columns excepted; through Aventara, a user's `role` is the one field a
+     * write may set.
+     */
+    readonly users?: boolean;
+    /**
+     * The organization plugin's `member` table (and its `organization`, read only):
+     * read as the rules grant; a membership may be created, removed, and its `role`
+     * changed. Needs `organization()` in `betterAuth.plugins`.
+     */
+    readonly members?: boolean;
+    /**
+     * Which Resource of the rules' schema is each of Better Auth's tables, by Better
+     * Auth model name (`{ user: "User", session: "AuthSession", jwks: null, … }`),
+     * `null` for a table the schema does not have (not "closed": a table the schema
+     * has is named, and closed or opened by its key). Each named Resource has every
+     * column of its table, by Better Auth's `fieldName`. Required, naming every table
+     * Better Auth is built with (its plugins' and Access's own included), when Better
+     * Auth does not run on its Prisma adapter and the rules have a schema: only the
+     * Prisma adapter ties a table to a model by name. Refused with the Prisma adapter.
+     */
+    readonly authTables?: {
+        readonly [model: string]: string | null;
+    };
+};
+/** The `resources` block, checked. */
+export type ResourcesChoice = {
+    readonly [K in AuthResourceKey]: boolean;
+} & {
+    readonly authTables: {
+        readonly [model: string]: string | null;
+    } | undefined;
+};
+/** The fields a write may set on one opened table, by action. */
+type WritableSets = {
+    readonly create: ReadonlySet<string>;
+    readonly update: ReadonlySet<string>;
+};
+/** The built-in rules over Better Auth's tables, as the engine runs them. */
+export type AuthTablesGuard = {
+    /** Denies added to the rules': closed tables, and the writes an opened one never takes. */
+    readonly denies: readonly AccessDenyRule[];
+    /** The secret columns, by Resource: never in an answer of `fieldsOf`. */
+    readonly sealed: ReadonlyMap<string, ReadonlySet<string>>;
+    /** The fields a write may set, by opened Resource. */
+    readonly writable: ReadonlyMap<string, WritableSets>;
+};
+/** The `resources` block, checked: `users` and `members` `true` or `false`, `authTables` a map of names or `null`. */
+export declare const checkResourcesOptions: (value: unknown) => ResourcesChoice;
+/**
+ * How the rules' schema names Better Auth's tables, checked when the instance is
+ * built: with Better Auth on its Prisma adapter, by the adapter's own delegates
+ * (and no `authTables`); else by `authTables`, which must name every table
+ * (`models`) and nothing else. A rules' schema with no Resource needs neither.
+ */
+export declare const authTableNaming: (input: {
+    readonly prisma: {
+        readonly usePlural: boolean;
+    } | undefined;
+    readonly authTables: ResourcesChoice["authTables"];
+    readonly models: readonly string[];
+    readonly schemaEmpty: boolean;
+}) => AuthTableNaming;
+/**
+ * The built-in rules for one set of rules: `resources` as the app gave it, Better
+ * Auth's tables as it is built (`authTablesOf`), and the rules' file. Throws
+ * `ACCESS_RESOURCE_MISSING` when a key's tables are missing, and
+ * `ACCESS_OPTIONS_INVALID` for a grant the built-in rules would leave without effect.
+ */
+export declare const guardAuthTables: (input: {
+    readonly resources: { readonly [K in AuthResourceKey]: boolean; };
+    readonly tables: ReadonlyMap<string, AuthTable>;
+    readonly naming: AuthTableNaming;
+    readonly policies: AccessPolicies;
+}) => AuthTablesGuard;
+/**
+ * `fieldsOf`'s answer with the built-in rules applied: a secret column is never
+ * listed, and a write lists only the fields its action may set on an opened table.
+ * `"all"` becomes the list it stands for (every field that is not governed) when
+ * something is taken out of it.
+ */
+export declare const guardedFields: (guard: AuthTablesGuard, question: AccessFieldsQuestion, answer: AccessFields, resource: {
+    readonly fields: readonly string[];
+    readonly governed: readonly string[];
+}) => AccessFields;
+export {};

package/dist/resources/auth-tables.guard.js

@@ -0,0 +1,405 @@
+// The built-in rules Access adds over Better Auth's tables, from the `resources` block
+// and the tables Better Auth is built with. The engine runs them beside the app's
+// rules, and they only narrow:
+//
+// - a table no `resources` key opens is closed: a deny on every action;
+// - an opened table takes the app's grants for reading, and only the writes its
+//   key allows (a deny on the other actions; the fields a write may set);
+// - a secret column (a password hash, a session token, a signing key) is never in
+//   an answer of `fieldsOf`, whatever the grants say: naming it is refused.
+//
+// At startup (the first read of `access.policy`, which is the framework's
+// construction), a key whose tables are missing (from Better Auth, or from the
+// rules' schema) is refused, and so is a grant that could never apply: one on a
+// closed table, or one naming a write the table never takes.
+import { AccessError } from "../access/access.error.js";
+import { ACTIONS } from "../policies.compiler.js";
+import { ownOf } from "../scope.resolver.js";
+import { KEY_TABLES, OPENED_TABLES, SECRET_COLUMNS, } from "./auth-tables.catalog.js";
+/** The prefix of the built-in deny ids, so `explain` and the audit log tell them from the rules'. */
+const BUILT_IN_ID = "better-auth:";
+const KEYS = ["users", "members"];
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+const missing = (message) => {
+    throw new AccessError("ACCESS_RESOURCE_MISSING", message);
+};
+/** The `resources` block, checked: `users` and `members` `true` or `false`, `authTables` a map of names or `null`. */
+export const checkResourcesOptions = (value) => {
+    if (value === undefined) {
+        return { users: false, members: false, authTables: undefined };
+    }
+    const shape = "`resources` is `{ users?: boolean, members?: boolean, authTables?: { [model]: Resource | null } }`: which of Better Auth's tables are Resources of the rules";
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return refuse(`${shape}.`);
+    }
+    const block = value;
+    for (const [key, on] of Object.entries(block)) {
+        if (key === "authTables") {
+            if (typeof on !== "object" || on === null || Array.isArray(on)) {
+                refuse(`${shape}; \`resources.authTables\` names each table's Resource, or \`null\`.`);
+            }
+            for (const [model, resource] of Object.entries(on)) {
+                if (resource !== null && typeof resource !== "string") {
+                    refuse(`${shape}; \`resources.authTables.${model}\` is a Resource's name or \`null\`.`);
+                }
+            }
+            continue;
+        }
+        if (!KEYS.includes(key)) {
+            refuse(`${shape}; it does not take \`${key}\`.`);
+        }
+        if (typeof on !== "boolean") {
+            refuse(`${shape}; \`resources.${key}\` was ${JSON.stringify(on)}.`);
+        }
+    }
+    return {
+        users: block.users === true,
+        members: block.members === true,
+        authTables: block.authTables,
+    };
+};
+/**
+ * How the rules' schema names Better Auth's tables, checked when the instance is
+ * built: with Better Auth on its Prisma adapter, by the adapter's own delegates
+ * (and no `authTables`); else by `authTables`, which must name every table
+ * (`models`) and nothing else. A rules' schema with no Resource needs neither.
+ */
+export const authTableNaming = (input) => {
+    const { prisma, authTables, models, schemaEmpty } = input;
+    if (prisma !== undefined) {
+        if (authTables !== undefined) {
+            refuse("`resources.authTables` is for Better Auth on another adapter than Prisma's: on Prisma's, Access finds each table by the Prisma model its adapter reads. Remove it.");
+        }
+        return { kind: "prisma", usePlural: prisma.usePlural };
+    }
+    if (schemaEmpty && authTables === undefined) {
+        return { kind: "map", map: {} };
+    }
+    const map = authTables ?? {};
+    const unnamed = [];
+    for (const model of models) {
+        if (!Object.hasOwn(map, model)) {
+            unnamed.push(model);
+        }
+    }
+    if (unnamed.length > 0) {
+        refuse(`Better Auth does not run on its Prisma adapter here, so nothing ties its tables to the rules' Resources by name (a Prisma schema can call any table anything, with \`@@map\`), and a table Access does not know would be an ordinary Resource, open to every grant, its secret columns included. Name the Resource each table is in \`resources.authTables\`, or \`null\` for a table the rules' schema does not have; it lacks ${unnamed.map((model) => `\`${model}\``).join(", ")}.`);
+    }
+    for (const model of Object.keys(map)) {
+        if (!models.includes(model)) {
+            refuse(`\`resources.authTables\` names \`${model}\`, which is no table of Better Auth's as it is built (its tables: ${models.join(", ")}).`);
+        }
+    }
+    return { kind: "map", map };
+};
+/** One Better Auth field's name in the app's schema, when the Resource has it. */
+const fieldOf = (table, facts, field) => {
+    const name = table.fields.get(field) ?? field;
+    return facts.fields.includes(name) ? name : undefined;
+};
+/**
+ * The fields a write may set: Better Auth's fields the catalog lists, the row's
+ * identifier for a create, and each relation whose reference fields are all among
+ * them (writing the relation writes those fields).
+ */
+const writableSet = (table, facts, fields, withIdentifier) => {
+    const set = new Set();
+    for (const field of fields ?? []) {
+        const name = fieldOf(table, facts, field);
+        if (name !== undefined) {
+            set.add(name);
+        }
+    }
+    if (fields !== undefined && withIdentifier) {
+        for (const field of facts.identifiers[0] ?? []) {
+            set.add(field);
+        }
+    }
+    for (const [relation, fact] of Object.entries(facts.relations)) {
+        if (fact.referenceFields?.every((field) => set.has(field))) {
+            set.add(relation);
+        }
+    }
+    return set;
+};
+const actionList = (actions) => actions.length === 1
+    ? (actions[0] ?? "")
+    : `${actions.slice(0, -1).join(", ")} and ${actions.at(-1)}`;
+/** Better Auth's columns of a table, as the app's schema names them (`fieldName`). */
+const columnsOf = (table) => {
+    const columns = [];
+    for (const name of table?.fields.values() ?? []) {
+        columns.push(name);
+    }
+    return columns;
+};
+/** Whether a Resource has every one of `columns` (and there is at least one). */
+const hasAll = (facts, columns) => {
+    for (const column of columns) {
+        if (!facts.fields.includes(column)) {
+            return false;
+        }
+    }
+    return columns.length > 0;
+};
+/**
+ * `resources.authTables`, held to the rules' schema: a table's Resource exists, is
+ * no other table's, and has every column of the table (by its `fieldName`); a table
+ * the map says the schema does not have (`null`) is not, column for column, a
+ * Resource the map leaves unnamed. A map that says otherwise than the schema would
+ * leave a table of Better Auth's an ordinary Resource.
+ */
+const checkAuthTablesMap = (map, tables, policies) => {
+    const named = new Map();
+    for (const [model, resource] of Object.entries(map)) {
+        if (resource === null) {
+            continue;
+        }
+        const facts = ownOf(policies.schema, resource);
+        if (facts === undefined) {
+            refuse(`\`resources.authTables\` puts Better Auth's \`${model}\` table in ${resource}, and the rules' schema has no ${resource}.`);
+        }
+        const other = named.get(resource);
+        if (other !== undefined) {
+            refuse(`\`resources.authTables\` puts Better Auth's \`${other}\` and \`${model}\` tables both in ${resource}.`);
+        }
+        named.set(resource, model);
+        const lacking = [];
+        for (const column of columnsOf(tables.get(model))) {
+            if (!facts?.fields.includes(column)) {
+                lacking.push(column);
+            }
+        }
+        if (lacking.length > 0) {
+            refuse(`\`resources.authTables\` puts Better Auth's \`${model}\` table in ${resource}, which lacks its columns ${lacking.join(", ")}: ${resource} is not that table, or names its columns otherwise than Better Auth's \`fieldName\`s say. Name the table's Resource, and its columns as Better Auth names them.`);
+        }
+    }
+    for (const [model, resource] of Object.entries(map)) {
+        if (resource !== null) {
+            continue;
+        }
+        const table = tables.get(model);
+        const columns = columnsOf(table);
+        const secrets = [];
+        for (const field of SECRET_COLUMNS[model] ?? []) {
+            secrets.push(table?.fields.get(field) ?? field);
+        }
+        for (const [other, facts] of Object.entries(policies.schema)) {
+            if (named.has(other)) {
+                continue;
+            }
+            const held = [];
+            let secret = false;
+            for (const column of columns) {
+                if (facts.fields.includes(column)) {
+                    held.push(column);
+                    secret ||= secrets.includes(column);
+                }
+            }
+            // Every column of the table, or one of its secrets with another of its
+            // columns beside it (a model that keeps only some): it may be the table.
+            if (hasAll(facts, columns) || (secret && held.length > 1)) {
+                refuse(`\`resources.authTables\` says the rules' schema does not have Better Auth's \`${model}\` table, and ${other} has columns of it (${held.join(", ")}), ${secret ? "a secret among them" : "every one"}. If ${other} is that table, name it: \`${model}: "${other}"\`; if it is your own, it cannot keep Better Auth's secret beside its columns.`);
+            }
+        }
+    }
+};
+/**
+ * On Prisma's adapter, refuses a table the adapter reads through a delegate no
+ * Resource answers to, while the schema has one that differs from it only in case
+ * or a plural `s`: the schema and the adapter disagree (an adapter without
+ * `usePlural` on a plural schema, say), and the table the adapter really reads is
+ * not certain to be closed.
+ */
+const refuseDisagreement = (tables, usePlural, policies) => {
+    for (const table of tables.values()) {
+        if (table.resource !== undefined) {
+            continue;
+        }
+        const delegate = (usePlural ? `${table.name}s` : table.name).toLowerCase();
+        for (const resource of Object.keys(policies.schema)) {
+            const lowered = resource.toLowerCase();
+            if (lowered === delegate ||
+                lowered === `${delegate}s` ||
+                `${lowered}s` === delegate) {
+                refuse(`Better Auth's Prisma adapter reads its \`${table.model}\` table as \`prisma.${usePlural ? `${table.name}s` : table.name}\`, and the rules' schema has no such model but has ${resource}: the schema and the adapter disagree (\`usePlural\`?). Make them agree, so Access knows which Resource is the table.`);
+            }
+        }
+    }
+};
+/** Whether a Resource's name is the ownership beacon's table's: `AventaraBeacon`, `_aventara_beacon`, their plurals, in any case. */
+const isBeaconName = (resource) => /^aventarabeacons?$/.test(resource.replace(/_/g, "").toLowerCase());
+/**
+ * Closes every Resource that is the ownership beacon's table, whoever's it is: the
+ * Access server's (Better Auth's `aventaraBeacon`, found as its tables are) and one
+ * that only looks like it by name (a service's own `_aventara_beacon` in the rules'
+ * schema). Each is denied every action and its `value` sealed, whatever grants
+ * name it (`"*"` included): any deny wins. A grant on the Access server's table is
+ * refused as on any closed Better Auth table. A beacon is read by the startup check
+ * through the service's own connection, never through a grant.
+ */
+const closeBeaconTables = (policies, tables, denies, sealed) => {
+    const found = tables.get(BEACON_TABLE_MODEL)?.resource;
+    for (const [resource, facts] of Object.entries(policies.schema)) {
+        if (facts.foreign !== undefined ||
+            (resource !== found && !isBeaconName(resource))) {
+            continue;
+        }
+        if (!denies.some((deny) => deny.id === `${BUILT_IN_ID}${resource}`)) {
+            denies.push({
+                id: `${BUILT_IN_ID}${resource}`,
+                actions: "*",
+                resource,
+            });
+        }
+        const secrets = new Set(sealed.get(resource) ?? []);
+        const value = resource === found
+            ? (tables.get(BEACON_TABLE_MODEL)?.fields.get("value") ?? "value")
+            : "value";
+        if (facts.fields.includes(value)) {
+            secrets.add(value);
+        }
+        if (secrets.size > 0) {
+            sealed.set(resource, secrets);
+        }
+    }
+};
+/** The Access server's beacon table, by Better Auth model name. */
+const BEACON_TABLE_MODEL = "aventaraBeacon";
+/**
+ * The built-in rules for one set of rules: `resources` as the app gave it, Better
+ * Auth's tables as it is built (`authTablesOf`), and the rules' file. Throws
+ * `ACCESS_RESOURCE_MISSING` when a key's tables are missing, and
+ * `ACCESS_OPTIONS_INVALID` for a grant the built-in rules would leave without effect.
+ */
+export const guardAuthTables = (input) => {
+    const { resources, tables, naming, policies } = input;
+    if (naming.kind === "map") {
+        checkAuthTablesMap(naming.map, tables, policies);
+    }
+    else {
+        refuseDisagreement(tables, naming.usePlural, policies);
+    }
+    for (const key of KEYS) {
+        if (!resources[key]) {
+            continue;
+        }
+        for (const model of KEY_TABLES[key]) {
+            const table = tables.get(model);
+            const plugin = OPENED_TABLES[model]?.plugin;
+            if (table === undefined) {
+                missing(`\`resources.${key}\` opens Better Auth's \`${model}\` table, and Better Auth has none${plugin === undefined ? "" : `: add ${plugin} to betterAuth.plugins`}.`);
+                continue;
+            }
+            const facts = table.resource === undefined
+                ? undefined
+                : ownOf(policies.schema, table.resource);
+            if (facts === undefined) {
+                missing(naming.kind === "prisma"
+                    ? `\`resources.${key}\` opens Better Auth's \`${model}\` table, and the rules' schema has no model Better Auth's Prisma adapter reads it through (\`prisma.${table.name}${naming.usePlural ? "s" : ""}\`). Run Better Auth's \`npx auth generate\`, then regenerate the model the rules are built from.`
+                    : `\`resources.${key}\` opens Better Auth's \`${model}\` table, and \`resources.authTables\` puts it in no Resource of the rules' schema. Name its Resource there.`);
+            }
+            if (facts?.foreign !== undefined) {
+                refuse(`\`resources.${key}\` opens Better Auth's \`${model}\` table as the Resource ${table.resource}, which the rules read as namespace "${facts.foreign}"'s (foreign). Open it in the service that owns it.`);
+            }
+        }
+    }
+    const denies = [];
+    const sealed = new Map();
+    const writable = new Map();
+    for (const table of tables.values()) {
+        const { resource } = table;
+        const facts = resource === undefined ? undefined : ownOf(policies.schema, resource);
+        if (resource === undefined ||
+            facts === undefined ||
+            facts.foreign !== undefined) {
+            continue;
+        }
+        const opened = OPENED_TABLES[table.model];
+        const open = opened !== undefined && resources[opened.key];
+        const secrets = [];
+        for (const field of SECRET_COLUMNS[table.model] ?? []) {
+            const name = fieldOf(table, facts, field);
+            if (name !== undefined) {
+                secrets.push(name);
+            }
+            else if (open) {
+                // An opened table's secret must be found to be sealed: one the schema
+                // names otherwise (a Prisma `@map`) would be readable.
+                refuse(`Better Auth's \`${table.model}\` table keeps a secret in \`${field}\`, and ${resource} has no field \`${table.fields.get(field) ?? field}\`: Access could not keep it sealed. Name the field as Better Auth's \`fieldName\` for it says, or leave the table closed.`);
+            }
+        }
+        if (secrets.length > 0) {
+            sealed.set(resource, new Set(secrets));
+        }
+        const grants = policies.grants.filter((grant) => grant.resource === resource);
+        if (opened === undefined || !open) {
+            denies.push({
+                id: `${BUILT_IN_ID}${resource}`,
+                actions: "*",
+                resource,
+            });
+            const [grant] = grants;
+            if (grant !== undefined) {
+                refuse(opened === undefined
+                    ? `the rules grant ${actionList(grant.actions)} on ${resource} (grant "${grant.id}"), Better Auth's \`${table.model}\` table, which Access keeps closed: no grant opens it. Remove the grant.`
+                    : `the rules grant ${actionList(grant.actions)} on ${resource} (grant "${grant.id}"), Better Auth's \`${table.model}\` table, which is closed until \`resources: { ${opened.key}: true }\` opens it as a Resource of the rules.`);
+            }
+            continue;
+        }
+        const { writes } = opened;
+        const refused = ACTIONS.filter((action) => (action === "create" && writes.create === undefined) ||
+            (action === "update" && writes.update === undefined) ||
+            (action === "delete" && !writes.delete));
+        if (refused.length > 0) {
+            denies.push({
+                id: `${BUILT_IN_ID}${resource}/${refused.join(",")}`,
+                actions: refused,
+                resource,
+            });
+        }
+        for (const grant of grants) {
+            const never = grant.actions.filter((action) => refused.includes(action));
+            if (never.length > 0) {
+                refuse(`the rules grant ${actionList(never)} on ${resource} (grant "${grant.id}"), Better Auth's \`${table.model}\` table, which Access never writes that way: a write through Aventara skips Better Auth's hooks and caches. Use Better Auth's own API for it, and remove ${actionList(never)} from the grant.`);
+            }
+        }
+        writable.set(resource, {
+            create: writableSet(table, facts, writes.create, true),
+            update: writableSet(table, facts, writes.update, false),
+        });
+    }
+    closeBeaconTables(policies, tables, denies, sealed);
+    return { denies, sealed, writable };
+};
+/**
+ * `fieldsOf`'s answer with the built-in rules applied: a secret column is never
+ * listed, and a write lists only the fields its action may set on an opened table.
+ * `"all"` becomes the list it stands for (every field that is not governed) when
+ * something is taken out of it.
+ */
+export const guardedFields = (guard, question, answer, resource) => {
+    const secrets = guard.sealed.get(question.resource);
+    const sets = question.access === "write"
+        ? guard.writable.get(question.resource)
+        : undefined;
+    const writes = sets === undefined || question.access !== "write"
+        ? undefined
+        : question.action === "create"
+            ? sets.create
+            : question.action === "update"
+                ? sets.update
+                : new Set([...sets.create].filter((field) => sets.update.has(field)));
+    if (secrets === undefined && writes === undefined) {
+        return answer;
+    }
+    const keeps = (field) => !(secrets?.has(field) ?? false) && (writes?.has(field) ?? true);
+    return {
+        always: answer.always === "all"
+            ? resource.fields.filter((field) => !resource.governed.includes(field) && keeps(field))
+            : answer.always.filter(keeps),
+        perRow: Object.fromEntries(Object.entries(answer.perRow).filter(([field]) => keeps(field))),
+    };
+};

package/dist/scope.resolver.d.ts

@@ -0,0 +1,138 @@
+import type { AccessAction, AccessComparison, AccessDenyRule, AccessGrantRule, AccessLiteral, AccessOrigin, AccessPolicies, AccessPredicate, AccessPrincipalCondition } from "./policies-contract.js";
+/**
+ * A row condition after the principal fold. `and` is a condition the author wrote
+ * as one object (the translator may write it back as one); `all` is a conjunction
+ * the engine builds (grant parts, a scope's grants and denies), always written as
+ * `AND`.
+ */
+export type Resolved = {
+    readonly k: "true";
+} | {
+    readonly k: "false";
+} | {
+    readonly k: "and" | "all" | "or";
+    readonly args: readonly Resolved[];
+} | {
+    readonly k: "not";
+    readonly arg: Resolved;
+} | {
+    readonly k: "cmp";
+    readonly field: string;
+    readonly cmp: AccessComparison;
+    readonly value: AccessLiteral | readonly AccessLiteral[];
+} | {
+    readonly k: "rel";
+    readonly relation: string;
+    readonly target: string;
+    readonly where: Resolved;
+} | {
+    readonly k: "some" | "every" | "none";
+    readonly relation: string;
+    readonly target: string;
+    readonly where: Resolved;
+};
+export declare const TRUE: Resolved;
+export declare const FALSE: Resolved;
+/** A conjunction the author wrote as one object. */
+export declare const andOf: (args: readonly Resolved[]) => Resolved;
+/** A conjunction the engine builds. */
+export declare const allOf: (args: readonly Resolved[]) => Resolved;
+export declare const orOf: (args: readonly Resolved[]) => Resolved;
+export declare const notOf: (arg: Resolved) => Resolved;
+type Schema = AccessPolicies["schema"];
+type Facts = Schema[string];
+/**
+ * A record's own member: `undefined` for a key the record only inherits
+ * (`constructor`, `toString`, `__proto__`), so no name in a file, a row or a principal
+ * ever reads `Object.prototype`. One signature per record of the file, not a generic
+ * one: each call would instantiate it, and the lookups are many.
+ */
+export declare function ownOf(record: Schema | undefined, key: string): Facts | undefined;
+export declare function ownOf(record: AccessPolicies["roles"] | undefined, key: string): AccessPolicies["roles"][string] | undefined;
+export declare function ownOf(record: Facts["relations"] | undefined, key: string): Facts["relations"][string] | undefined;
+export declare function ownOf(record: Facts["types"] | undefined, key: string): NonNullable<Facts["types"]>[string] | undefined;
+export declare function ownOf(record: AccessPolicies["claims"] | undefined, key: string): AccessPolicies["claims"][string] | undefined;
+export declare function ownOf(record: {
+    readonly [key: string]: readonly string[];
+} | undefined, key: string): readonly string[] | undefined;
+/** A plain object: made by `{}` or JSON, not an array, a `Date`, a `Map` or a class instance. */
+export declare const isPlainObject: (value: unknown) => value is {
+    readonly [key: string]: unknown;
+};
+/** What every question states about who asks. */
+export type PrincipalFacts = {
+    /** The principal: an object, or `null` (anonymous). */
+    readonly principal: {
+        readonly [key: string]: unknown;
+    } | null;
+    readonly origin: AccessOrigin;
+};
+/**
+ * Reads the principal off a question: any object, an instance of a class included
+ * (an entity), is a principal; an array, a function or a primitive is anonymous.
+ */
+export declare const principalFactsOf: (principal: unknown, origin: AccessOrigin) => PrincipalFacts;
+/**
+ * Folds a condition on the principal alone (claims, origin) to a boolean. A claim
+ * the principal lacks, or holds as another type, fails closed: a grant's global role
+ * is not held, and a deny's `if` holds, whatever value it compares with. Access mints
+ * every declared boolean claim, `false` when unset, so a token it issued lacks none;
+ * a foreign or stale token without `banned` is denied by `banned: true`. The
+ * anonymous caller is the one exception: a comparison with `true` never holds for it.
+ */
+export declare const foldPrincipalCondition: (condition: AccessPrincipalCondition, facts: PrincipalFacts, rule: "grant" | "deny") => boolean;
+/**
+ * How a rule reads a `me` value the principal lacks. A grant drops: it never
+ * matches, whatever `NOT` surrounds the value. A deny matches as a whole, whatever
+ * `not` or `NOT` surrounds the value. Both fail closed.
+ */
+export type MissingMode = "drop-rule" | "match-rule";
+/**
+ * Substitutes the principal into a row condition. A `me` value the principal lacks
+ * makes the whole rule `false` for a grant (`drop-rule`) and `true` for a deny
+ * (`match-rule`).
+ */
+export declare const resolvePredicate: (policies: AccessPolicies, predicate: AccessPredicate, facts: PrincipalFacts, mode: MissingMode) => Resolved;
+/**
+ * The grants and denies a question about `action` on `resource` reads. A grant on
+ * `"*"` reaches the file's own Resources only: never a foreign one, and never one
+ * its schema does not list. A deny on `"*"` reaches every Resource.
+ */
+export declare const rulesFor: (policies: AccessPolicies, resource: string, action: AccessAction) => {
+    grants: AccessGrantRule[];
+    denies: AccessDenyRule[];
+};
+/** One grant, for one of its subjects, folded for the principal. */
+export type FoldedGrant = {
+    readonly grant: AccessGrantRule;
+    readonly subject: string;
+    readonly condition: Resolved;
+};
+/**
+ * Each grant's condition per subject: its `where`, then the subject's (its row
+ * role, through `in`), then, with `after`, the `after` condition. A grant that reads
+ * a `me` value the principal lacks drops.
+ */
+export declare const foldGrants: (policies: AccessPolicies, grants: readonly AccessGrantRule[], facts: PrincipalFacts, withAfter?: boolean) => FoldedGrant[];
+/** One deny, folded for the principal. */
+export type FoldedDeny = {
+    readonly deny: AccessDenyRule;
+    readonly condition: Resolved;
+};
+/**
+ * Each deny's row condition: `false` when its `if` does not hold for this principal,
+ * `true` when its `where` reads a `me` value the principal lacks.
+ */
+export declare const foldDenies: (policies: AccessPolicies, denies: readonly AccessDenyRule[], facts: PrincipalFacts) => FoldedDeny[];
+/** The rows a principal may `action`: OR of the grants, AND NOT each deny. */
+export declare const scopeCondition: (grants: readonly FoldedGrant[], denies: readonly FoldedDeny[]) => Resolved;
+/**
+ * A folded condition on `resource` in the form a database reads as `can` does.
+ * `can` reads a comparison on a NULL field as false, so its `NOT` keeps the row; SQL
+ * reads it as unknown, and its `NOT` drops the row. Each negated comparison on a
+ * nullable field (the schema entry's `nullable`) gets its own guard, `NOT (f = v) OR
+ * f IS NULL`, and a negated to-one step whose reference is nullable gets `OR fk IS
+ * NULL`. A condition with neither is returned as it is.
+ */
+export declare const nullSafe: (policies: AccessPolicies, resource: string, node: Resolved) => Resolved;
+export {};