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

package/dist/scope.resolver.d.ts

@@ -0,0 +1,144 @@
+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 Resource's governed fields for one access: each field `govern` lists, except one
+ * `governModes` governs for the other access only (`"write"` is read as any other
+ * field, `"read"` written as any other). A field with no mode is governed for both.
+ */
+export declare const governedFor: (policies: Pick<AccessPolicies, "govern" | "governModes">, resource: string, access: "read" | "write") => readonly string[];
+/** 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 {};

package/dist/scope.resolver.js

@@ -0,0 +1,529 @@
+// The principal fold: substitute the principal into every rule, fold what
+// the principal alone decides (claims, origin, `signedIn`), expand roles, and keep only
+// row conditions. Grants combine with OR, denies with AND NOT. What leaves this module
+// holds literals only.
+export const TRUE = { k: "true" };
+export const FALSE = { k: "false" };
+const junction = (k, args) => {
+    const kept = [];
+    for (const arg of args) {
+        if (arg.k === "false") {
+            return FALSE;
+        }
+        if (arg.k !== "true") {
+            kept.push(arg);
+        }
+    }
+    if (kept.length === 0) {
+        return TRUE;
+    }
+    return kept.length === 1 ? kept[0] : { k, args: kept };
+};
+/** A conjunction the author wrote as one object. */
+export const andOf = (args) => junction("and", args);
+/** A conjunction the engine builds. */
+export const allOf = (args) => junction("all", args);
+export const orOf = (args) => {
+    const kept = [];
+    for (const arg of args) {
+        if (arg.k === "true") {
+            return TRUE;
+        }
+        if (arg.k !== "false") {
+            kept.push(arg);
+        }
+    }
+    if (kept.length === 0) {
+        return FALSE;
+    }
+    return kept.length === 1 ? kept[0] : { k: "or", args: kept };
+};
+export const notOf = (arg) => arg.k === "true" ? FALSE : arg.k === "false" ? TRUE : { k: "not", arg };
+export function ownOf(record, key) {
+    return record !== undefined && Object.hasOwn(record, key)
+        ? record[key]
+        : undefined;
+}
+/**
+ * A Resource's governed fields for one access: each field `govern` lists, except one
+ * `governModes` governs for the other access only (`"write"` is read as any other
+ * field, `"read"` written as any other). A field with no mode is governed for both.
+ */
+export const governedFor = (policies, resource, access) => {
+    const fields = ownOf(policies.govern, resource);
+    const modes = policies.governModes !== undefined &&
+        Object.hasOwn(policies.governModes, resource)
+        ? policies.governModes[resource]
+        : undefined;
+    if (fields === undefined || modes === undefined) {
+        return fields ?? [];
+    }
+    const other = access === "read" ? "write" : "read";
+    return fields.filter((field) => !(Object.hasOwn(modes, field) && modes[field] === other));
+};
+/** A plain object: made by `{}` or JSON, not an array, a `Date`, a `Map` or a class instance. */
+export const isPlainObject = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+/**
+ * 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 const principalFactsOf = (principal, origin) => ({
+    principal: typeof principal === "object" &&
+        principal !== null &&
+        !Array.isArray(principal)
+        ? principal
+        : null,
+    origin,
+});
+/** The value at `path`, through own members only; `undefined` where one is missing. */
+const readPath = (from, path) => {
+    let value = from;
+    for (const key of path) {
+        if (typeof value !== "object" ||
+            value === null ||
+            !Object.hasOwn(value, key)) {
+            return undefined;
+        }
+        value = value[key];
+    }
+    return value;
+};
+/**
+ * A `me` value the principal does not have: anonymous, a missing or null property,
+ * an empty string (no identity is `""`), a number JSON cannot carry, or anything but
+ * a string, number or boolean.
+ */
+class MissingPrincipalValue extends Error {
+}
+const literalOf = (operand, facts) => {
+    if (operand === null || typeof operand !== "object") {
+        return operand;
+    }
+    const value = facts.principal === null
+        ? undefined
+        : readPath(facts.principal, operand.principal);
+    if (value === "" ||
+        (typeof value === "number" && !Number.isFinite(value)) ||
+        (typeof value !== "string" &&
+            typeof value !== "number" &&
+            typeof value !== "boolean")) {
+        throw new MissingPrincipalValue();
+    }
+    return value;
+};
+/** A condition on the principal, three-valued: a claim it lacks is `"unknown"`. */
+const principalTruth = (condition, facts) => {
+    switch (condition.op) {
+        case "and": {
+            let unknown = false;
+            for (const arg of condition.args) {
+                const truth = principalTruth(arg, facts);
+                if (truth === false) {
+                    return false;
+                }
+                unknown ||= truth === "unknown";
+            }
+            return unknown ? "unknown" : true;
+        }
+        case "origin":
+            return facts.origin === condition.value;
+        case "cmp": {
+            if (facts.principal === null) {
+                // The anonymous caller has no token, so none can be stale: no flag is set on
+                // it (a ban does not close an `anyone` grant), and any other claim is unknown.
+                return condition.value === true ? false : "unknown";
+            }
+            const value = readPath(facts.principal, ["claims", ...condition.claim]);
+            if (value === undefined || value === null) {
+                return "unknown";
+            }
+            return typeof value === typeof condition.value
+                ? value === condition.value
+                : "unknown";
+        }
+    }
+};
+/**
+ * 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 const foldPrincipalCondition = (condition, facts, rule) => {
+    const truth = principalTruth(condition, facts);
+    return truth === "unknown" ? rule === "deny" : truth;
+};
+const resolveIn = (policies, predicate, facts, mode) => {
+    switch (predicate.op) {
+        case "true":
+            return TRUE;
+        case "false":
+            return FALSE;
+        case "and":
+            return andOf(predicate.args.map((arg) => resolveIn(policies, arg, facts, mode)));
+        case "or":
+            return orOf(predicate.args.map((arg) => resolveIn(policies, arg, facts, mode)));
+        case "not":
+            return notOf(resolveIn(policies, predicate.arg, facts, mode));
+        case "cmp": {
+            const value = Array.isArray(predicate.value)
+                ? predicate.value.map((item) => literalOf(item, facts))
+                : literalOf(predicate.value, facts);
+            return { k: "cmp", field: predicate.field, cmp: predicate.cmp, value };
+        }
+        case "rel": {
+            const where = resolveIn(policies, predicate.where, facts, mode);
+            return where.k === "false"
+                ? FALSE
+                : {
+                    k: "rel",
+                    relation: predicate.relation,
+                    target: predicate.target,
+                    where,
+                };
+        }
+        case "some":
+        case "every":
+        case "none": {
+            const where = resolveIn(policies, predicate.where, facts, mode);
+            if (predicate.op === "some" && where.k === "false") {
+                return FALSE;
+            }
+            if (predicate.op === "none" && where.k === "false") {
+                return TRUE;
+            }
+            if (predicate.op === "every" && where.k === "true") {
+                return TRUE;
+            }
+            return {
+                k: predicate.op,
+                relation: predicate.relation,
+                target: predicate.target,
+                where,
+            };
+        }
+        case "role": {
+            const role = ownOf(policies.roles, predicate.role);
+            if (role === undefined || !("on" in role)) {
+                return FALSE;
+            }
+            return resolveIn(policies, role.where, facts, mode);
+        }
+    }
+};
+/**
+ * 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 const resolvePredicate = (policies, predicate, facts, mode) => {
+    try {
+        return resolveIn(policies, predicate, facts, mode);
+    }
+    catch (error) {
+        if (error instanceof MissingPrincipalValue) {
+            return mode === "drop-rule" ? FALSE : TRUE;
+        }
+        throw error;
+    }
+};
+/** Whether a rule names this action on this Resource. */
+const covers = (resource, action, rule) => (rule.resource === resource || rule.resource === "*") &&
+    (rule.actions === "*" || rule.actions.includes(action));
+/**
+ * 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 const rulesFor = (policies, resource, action) => {
+    const facts = ownOf(policies.schema, resource);
+    const own = facts !== undefined && facts.foreign === undefined;
+    return {
+        grants: policies.grants.filter((grant) => (own || grant.resource !== "*") && covers(resource, action, grant)),
+        denies: policies.denies.filter((deny) => covers(resource, action, deny)),
+    };
+};
+/** What a subject contributes to a grant, folded: `true`, `false` or a row condition. */
+const subjectCondition = (policies, grant, subject, facts) => {
+    if (subject === "anyone") {
+        return TRUE;
+    }
+    if (subject === "signedIn") {
+        return facts.principal === null ? FALSE : TRUE;
+    }
+    const role = ownOf(policies.roles, subject);
+    if (role === undefined) {
+        return FALSE;
+    }
+    if ("global" in role) {
+        return foldPrincipalCondition(role.global, facts, "grant") ? TRUE : FALSE;
+    }
+    const held = { op: "role", role: subject };
+    const predicate = grant.in === undefined
+        ? held
+        : { op: "rel", relation: grant.in, target: role.on, where: held };
+    return resolvePredicate(policies, predicate, facts, "drop-rule");
+};
+/**
+ * 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 const foldGrants = (policies, grants, facts, withAfter = false) => grants.flatMap((grant) => grant.subjects.map((subject) => {
+    const parts = [];
+    if (grant.where !== undefined) {
+        parts.push(resolvePredicate(policies, grant.where, facts, "drop-rule"));
+    }
+    parts.push(subjectCondition(policies, grant, subject, facts));
+    if (withAfter && grant.after !== undefined) {
+        parts.push(resolvePredicate(policies, grant.after, facts, "drop-rule"));
+    }
+    return { grant, subject, condition: allOf(parts) };
+}));
+/**
+ * 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 const foldDenies = (policies, denies, facts) => denies.map((deny) => {
+    if (deny.if !== undefined &&
+        !foldPrincipalCondition(deny.if, facts, "deny")) {
+        return { deny, condition: FALSE };
+    }
+    return {
+        deny,
+        condition: deny.where === undefined
+            ? TRUE
+            : resolvePredicate(policies, deny.where, facts, "match-rule"),
+    };
+});
+/** The rows a principal may `action`: OR of the grants, AND NOT each deny. */
+export const scopeCondition = (grants, denies) => {
+    const allowed = orOf(grants.map((grant) => grant.condition));
+    if (allowed.k === "false") {
+        return FALSE;
+    }
+    return allOf([allowed, ...denies.map((deny) => notOf(deny.condition))]);
+};
+/** Whether the schema entry lists `field` as nullable. A file without `nullable` has none. */
+const nullableIn = (policies, resource, field) => ownOf(policies.schema, resource)?.nullable?.includes(field) === true;
+/**
+ * Whether a to-one step can find no row: `"nullable"` when one of its reference
+ * fields is nullable, `"required"` when it holds references and none is, and
+ * `"unstated"` for the end that holds no references (the other end's step).
+ */
+const stepKind = (policies, resource, node) => {
+    const fields = ownOf(ownOf(policies.schema, resource)?.relations, node.relation)?.referenceFields;
+    if (fields === undefined) {
+        return "unstated";
+    }
+    return fields.some((field) => nullableIn(policies, resource, field))
+        ? "nullable"
+        : "required";
+};
+/**
+ * Whether SQL can read a comparison as unknown where `can` reads it as false: a
+ * nullable field compared with a value (SQL's `NULL = v` is unknown; `f = NULL` is
+ * written `IS NULL` and never is), or an `in` list that holds `null`.
+ */
+const unknownIn = (policies, resource, node) => Array.isArray(node.value)
+    ? node.value.includes(null) ||
+        nullableIn(policies, resource, node.field)
+    : node.value !== null && nullableIn(policies, resource, node.field);
+/** Whether SQL reads `node` exactly as `can` does: no unknown comparison, no step that can find no row. */
+const known = (policies, resource, node) => {
+    switch (node.k) {
+        case "true":
+        case "false":
+            return true;
+        case "cmp":
+            return !unknownIn(policies, resource, node);
+        case "and":
+        case "all":
+        case "or":
+            return node.args.every((arg) => known(policies, resource, arg));
+        case "not":
+            return known(policies, resource, node.arg);
+        case "rel":
+            return (stepKind(policies, resource, node) !== "nullable" &&
+                known(policies, node.target, node.where));
+        case "some":
+        case "every":
+        case "none":
+            return known(policies, node.target, node.where);
+    }
+};
+/**
+ * A comparison with the `null`s taken out of its `in` list: `can` never matches a
+ * NULL field through a list, and SQL's `IN (NULL, …)` is unknown for every row. A
+ * list left empty: `in` matches no row; `notIn` every row whose field is not NULL,
+ * which on a required field is every row.
+ */
+const listWithoutNull = (policies, resource, node) => {
+    if (!Array.isArray(node.value)) {
+        return node;
+    }
+    const value = [];
+    for (const item of node.value) {
+        if (item !== null) {
+            value.push(item);
+        }
+    }
+    if (value.length > 0) {
+        return { k: "cmp", field: node.field, cmp: node.cmp, value };
+    }
+    if (node.cmp === "in") {
+        return FALSE;
+    }
+    return nullableIn(policies, resource, node.field)
+        ? { k: "cmp", field: node.field, cmp: "ne", value: null }
+        : TRUE;
+};
+const isNull = (field) => ({
+    k: "cmp",
+    field,
+    cmp: "eq",
+    value: null,
+});
+/** The same to-one step, around another condition. */
+const step = (node, where) => ({
+    k: "rel",
+    relation: node.relation,
+    target: node.target,
+    where,
+});
+/** A quantifier over the same to-many relation. */
+const quantified = (k, node, where) => ({ k, relation: node.relation, target: node.target, where });
+/** One rewrite applied to each condition of a list. */
+const each = (rewrite, policies, resource, nodes) => {
+    const out = [];
+    for (const node of nodes) {
+        out.push(rewrite(policies, resource, node));
+    }
+    return out;
+};
+/** The condition, true on exactly the rows where `can` reads it as true. */
+const holds = (policies, resource, node) => {
+    if (known(policies, resource, node)) {
+        return node;
+    }
+    switch (node.k) {
+        case "true":
+        case "false":
+            return node;
+        case "cmp":
+            return listWithoutNull(policies, resource, node);
+        case "and":
+            return andOf(each(holds, policies, resource, node.args));
+        case "all":
+            return allOf(each(holds, policies, resource, node.args));
+        case "or":
+            return orOf(each(holds, policies, resource, node.args));
+        case "not":
+            return fails(policies, resource, node.arg);
+        case "rel":
+            // A step that finds no row is false, in SQL as in `can`.
+            return step(node, holds(policies, node.target, node.where));
+        case "some":
+        case "none":
+            // `EXISTS` and `NOT EXISTS`: true or false around the rows they count.
+            return quantified(node.k, node, holds(policies, node.target, node.where));
+        case "every":
+            // An ORM may write `every` as `NOT EXISTS (… WHERE NOT condition)`, where an
+            // unknown condition passes: ask that no related row fails it instead.
+            return quantified("none", node, fails(policies, node.target, node.where));
+    }
+};
+/** The condition's negation, true on exactly the rows where `can` reads it as false. */
+const fails = (policies, resource, node) => {
+    if (known(policies, resource, node)) {
+        return notOf(node);
+    }
+    switch (node.k) {
+        case "true":
+        case "false":
+            return notOf(node);
+        case "cmp": {
+            const negated = notOf(listWithoutNull(policies, resource, node));
+            return nullableIn(policies, resource, node.field)
+                ? orOf([negated, isNull(node.field)])
+                : negated;
+        }
+        case "and":
+        case "all": {
+            // Comparisons only: `NOT (a AND b) OR a IS NULL OR b IS NULL`.
+            if (node.args.every((arg) => arg.k === "cmp")) {
+                const comparisons = node.args;
+                const guards = [];
+                const guarded = [];
+                for (const arg of comparisons) {
+                    if (arg.value !== null &&
+                        nullableIn(policies, resource, arg.field) &&
+                        !guarded.includes(arg.field)) {
+                        guarded.push(arg.field);
+                        guards.push(isNull(arg.field));
+                    }
+                }
+                const lists = [];
+                for (const arg of comparisons) {
+                    lists.push(listWithoutNull(policies, resource, arg));
+                }
+                const strict = (node.k === "and" ? andOf : allOf)(lists);
+                return orOf([notOf(strict), ...guards]);
+            }
+            return orOf(each(fails, policies, resource, node.args));
+        }
+        case "or":
+            return allOf(each(fails, policies, resource, node.args));
+        case "not":
+            return holds(policies, resource, node.arg);
+        case "rel": {
+            const failing = step(node, fails(policies, node.target, node.where));
+            switch (stepKind(policies, resource, node)) {
+                case "required":
+                    // The row is always there: the step fails where its condition does.
+                    return failing;
+                case "nullable": {
+                    // No row (a NULL reference) fails it too, said on this row's own fields.
+                    const references = ownOf(ownOf(policies.schema, resource)?.relations, node.relation)
+                        ?.referenceFields ?? [];
+                    const guards = [];
+                    for (const field of references) {
+                        guards.push(isNull(field));
+                    }
+                    guards.push(failing);
+                    return orOf(guards);
+                }
+                case "unstated":
+                    // No reference fields here to say "no row" with: the `NOT` of the step
+                    // covers the missing row, the failing condition the row that is there.
+                    return orOf([
+                        notOf(step(node, holds(policies, node.target, node.where))),
+                        failing,
+                    ]);
+            }
+            return failing;
+        }
+        case "some":
+        case "none":
+            return notOf(quantified(node.k, node, holds(policies, node.target, node.where)));
+        case "every":
+            return quantified("some", node, fails(policies, node.target, node.where));
+    }
+};
+/**
+ * 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 const nullSafe = (policies, resource, node) => holds(policies, resource, node);

package/dist/sha256.digest.d.ts

@@ -0,0 +1,2 @@
+/** The SHA-256 digest of `text`'s UTF-8 bytes, as 64 lowercase hex digits. */
+export declare const sha256Hex: (text: string) => string;