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

package/dist/predicate.evaluator.js

@@ -0,0 +1,378 @@
+// In-memory evaluation of a folded condition against a row's own scalar fields, and
+// the `exists` questions for the rest. A to-one step whose references the row carries
+// is asked on the row they name, with the row's values; whatever else an existing row
+// leaves is asked about the row itself, by its identifier. A relation member on the
+// row is never read: core strips them, and any other caller could have forged one.
+// What cannot be asked is unknown, and the caller fails closed on it.
+import { mergeWhere, translateWhere, } from "./aventara-where.translator.js";
+import { allOf, andOf, FALSE, notOf, nullSafe, orOf, ownOf, TRUE, } from "./scope.resolver.js";
+/** The type `can` compares `field` of `resource` by. */
+const typeOf = (policies, resource, field) => ownOf(ownOf(policies.schema, resource)?.types, field);
+const DECIMAL = /^([+-]?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+/**
+ * A decimal's value as `{ sign, digits, point }`: `0.<digits> × 10^point`, with no
+ * leading or trailing zero in `digits` (zero is `{ sign: "", digits: "", point: 0 }`).
+ * `undefined` for text that is no decimal.
+ */
+export const decimalParts = (text) => {
+    const match = DECIMAL.exec(text);
+    if (match === null) {
+        return undefined;
+    }
+    // Indexed, not destructured: destructuring a match costs the type checker its
+    // iterator types (about 1,000 instantiations, the type budget's whole margin).
+    const sign = match[1] ?? "";
+    const whole = match[2] ?? "";
+    const fraction = match[3] ?? "";
+    const exponent = match[4] ?? "0";
+    const shift = Number(exponent);
+    if (!Number.isSafeInteger(shift)) {
+        return undefined;
+    }
+    let digits = whole + fraction;
+    let point = whole.length + shift;
+    const leading = digits.length - digits.replace(/^0+/, "").length;
+    digits = digits.slice(leading).replace(/0+$/, "");
+    point -= leading;
+    return digits === ""
+        ? { sign: "", digits: "", point: 0 }
+        : { sign: sign === "-" ? "-" : "", digits, point };
+};
+/**
+ * An ISO-8601 date, or date and time with its offset (never a local time), to the
+ * millisecond at most.
+ */
+const INSTANT = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|([+-])(\d{2}):(\d{2})))?$/;
+/**
+ * The epoch milliseconds of an ISO-8601 string that reads back as written: no
+ * February 30th, no hour 24, no offset past 23:59, nothing past the millisecond.
+ */
+const instantOfText = (text) => {
+    const match = INSTANT.exec(text);
+    if (match === null) {
+        return undefined;
+    }
+    const part = (index) => Number(match[index] ?? "0");
+    const year = part(1);
+    const month = part(2);
+    const day = part(3);
+    const hour = part(4);
+    const minute = part(5);
+    const second = part(6);
+    const millisecond = Number((match[7] ?? "").padEnd(3, "0"));
+    const local = Date.UTC(year, month - 1, day, hour, minute, second, millisecond);
+    const read = new Date(local);
+    if (read.getUTCFullYear() !== year ||
+        read.getUTCMonth() !== month - 1 ||
+        read.getUTCDate() !== day ||
+        read.getUTCHours() !== hour ||
+        read.getUTCMinutes() !== minute ||
+        read.getUTCSeconds() !== second ||
+        part(10) > 23 ||
+        part(11) > 59) {
+        return undefined;
+    }
+    const offset = (part(10) * 60 + part(11)) * 60_000;
+    return match[9] === "-" ? local + offset : local - offset;
+};
+/** An instant's epoch milliseconds, from a valid `Date` or an ISO-8601 string that reads back as written. */
+export const instantOf = (value) => {
+    if (value instanceof Date) {
+        const time = value.getTime();
+        return Number.isNaN(time) ? undefined : time;
+    }
+    return typeof value === "string" ? instantOfText(value) : undefined;
+};
+/** A decimal object's text: core's `AvDecimal`, an ORM's decimal, anything whose `toString()` is decimal digits. */
+const decimalText = (value) => typeof value === "string"
+    ? value
+    : typeof value === "number"
+        ? Number.isFinite(value)
+            ? String(value)
+            : undefined
+        : typeof value === "object" &&
+            value !== null &&
+            !(value instanceof Date) &&
+            !Array.isArray(value)
+            ? String(value)
+            : undefined;
+/**
+ * The key a value is compared by, for a field of `type`: equal keys, equal values.
+ * `undefined` when the value is not one of the type's (a type mismatch).
+ */
+const comparisonKey = (value, type) => {
+    switch (type) {
+        case "decimal": {
+            const text = decimalText(value);
+            const parts = text === undefined ? undefined : decimalParts(text);
+            return parts === undefined
+                ? undefined
+                : `${parts.sign}${parts.digits}@${parts.point}`;
+        }
+        case "datetime":
+            return instantOf(value);
+        case "bigint":
+            return typeof value === "bigint"
+                ? value
+                : typeof value === "number" && Number.isSafeInteger(value)
+                    ? BigInt(value)
+                    : typeof value === "string" && /^-?\d+$/.test(value)
+                        ? BigInt(value)
+                        : undefined;
+        default:
+            return typeof value === "string" ||
+                typeof value === "boolean" ||
+                (typeof value === "number" && Number.isFinite(value))
+                ? value
+                : undefined;
+    }
+};
+/**
+ * One comparison of a row's value with a rule's, three-valued: a value of another
+ * type than the field's, or than the rule's, is `"unknown"`.
+ */
+const compare = (rowValue, cmp, value, type) => {
+    if (rowValue === null) {
+        // A comparison on NULL is false, except `equals: null` (IS NULL); a list never
+        // holds it for `can`.
+        return cmp === "eq" && value === null;
+    }
+    const actual = comparisonKey(rowValue, type);
+    const equal = (literal) => {
+        const expected = comparisonKey(literal, type);
+        return actual === undefined ||
+            expected === undefined ||
+            typeof actual !== typeof expected
+            ? "unknown"
+            : actual === expected;
+    };
+    if (cmp === "eq" || cmp === "ne") {
+        if (value === null) {
+            return cmp === "ne";
+        }
+        const truth = equal(value);
+        return truth === "unknown" ? truth : cmp === "eq" ? truth : !truth;
+    }
+    let unknown = false;
+    for (const literal of value) {
+        if (literal === null) {
+            continue;
+        }
+        const truth = equal(literal);
+        if (truth === true) {
+            return cmp === "in";
+        }
+        unknown ||= truth === "unknown";
+    }
+    return unknown ? "unknown" : cmp === "notIn";
+};
+const UNKNOWN = { k: "unknown" };
+/**
+ * A conjunction, three-valued. A part that is unknown makes the whole unknown unless
+ * another part is false: an unknown never waits on an `exists` question, and the
+ * caller fails closed on it.
+ */
+const and3 = (k, args) => args.some((arg) => arg.k === "false")
+    ? FALSE
+    : args.some((arg) => arg.k === "unknown")
+        ? UNKNOWN
+        : (k === "and" ? andOf : allOf)(args);
+const or3 = (args) => args.some((arg) => arg.k === "true")
+    ? TRUE
+    : args.some((arg) => arg.k === "unknown")
+        ? UNKNOWN
+        : orOf(args);
+/** A row's own field: an inherited one is not on the row. */
+const fieldOf = (row, field) => Object.hasOwn(row, field) ? row[field] : undefined;
+/**
+ * Evaluates what the row carries. The answer is `TRUE`, `FALSE`, `UNKNOWN` (a value
+ * of another type than its field's), or the residual condition: the part the row
+ * could not decide, with the decided parts folded away. A relation member on the row
+ * is ignored: every relation step stays whole in the residual, for `exists`. Each comparison is made by its
+ * field's type (`types`): a decimal by its digits, a datetime by its instant, a
+ * bigint exactly.
+ */
+export const evaluateOnRow = (policies, resource, node, row) => {
+    switch (node.k) {
+        case "true":
+        case "false":
+            return node;
+        case "and":
+        case "all":
+            return and3(node.k, node.args.map((arg) => evaluateOnRow(policies, resource, arg, row)));
+        case "or":
+            return or3(node.args.map((arg) => evaluateOnRow(policies, resource, arg, row)));
+        case "not": {
+            const arg = evaluateOnRow(policies, resource, node.arg, row);
+            return arg.k === "unknown" ? arg : notOf(arg);
+        }
+        case "cmp": {
+            const value = fieldOf(row, node.field);
+            if (value === undefined) {
+                return node;
+            }
+            const truth = compare(value, node.cmp, node.value, typeOf(policies, resource, node.field));
+            return truth === "unknown" ? UNKNOWN : truth ? TRUE : FALSE;
+        }
+        case "rel":
+        case "some":
+        case "every":
+        case "none":
+            // A relation is never read off the row: whoever built the row could have put
+            // anything there. It is decided through the row's identifier or references
+            // and `exists`, on what the database holds.
+            return node;
+    }
+};
+const ask = async (context, resource, where) => {
+    if (context.exists === undefined) {
+        return "unknown";
+    }
+    const answer = (await context.exists(resource, where)) === true;
+    context.lookups.push({ resource, where, answer });
+    return answer;
+};
+/** An `exists` question's `where`: the row's own keys and the residual, null-safe. */
+const combine = (policies, resource, where, residual) => {
+    const condition = translateWhere(nullSafe(policies, resource, residual));
+    return mergeWhere([where, condition]) ?? { AND: [where, condition] };
+};
+/** A row's value as an `exists` question's `where` states it: a `Date` as its ISO instant, a bigint as itself (exact). */
+const whereValue = (value) => value instanceof Date ? value.toISOString() : value;
+/** Asks about an existing row, by its first identifier the row carries in full. */
+const askByIdentifier = async (context, resource, residual) => {
+    const identifiers = ownOf(context.policies.schema, resource)?.identifiers ?? [];
+    const identifier = identifiers.find((fields) => fields.every((field) => fieldOf(context.row, field) !== undefined &&
+        fieldOf(context.row, field) !== null));
+    if (identifier === undefined) {
+        return "unknown";
+    }
+    const where = Object.fromEntries(identifier.map((field) => [
+        field,
+        { equals: whereValue(fieldOf(context.row, field)) },
+    ]));
+    return ask(context, resource, combine(context.policies, resource, where, residual));
+};
+/**
+ * The reference values a to-one step's relation takes from the row: `undefined` when
+ * this end holds no references, or the row does not carry them all.
+ */
+const carriedReferences = (context, resource, node) => {
+    const relation = ownOf(ownOf(context.policies.schema, resource)?.relations, node.relation);
+    if (relation?.referenceFields === undefined ||
+        relation.references === undefined) {
+        return undefined;
+    }
+    const values = relation.referenceFields.map((field) => fieldOf(context.row, field));
+    return values.some((value) => value === undefined)
+        ? undefined
+        : { references: relation.references, values };
+};
+/** Whether a residual holds, outside any relation, a to-one step the row's references decide. */
+const stepsByReference = (context, resource, node) => {
+    switch (node.k) {
+        case "and":
+        case "all":
+        case "or":
+            return node.args.some((arg) => stepsByReference(context, resource, arg));
+        case "not":
+            return stepsByReference(context, resource, node.arg);
+        case "rel":
+            return carriedReferences(context, resource, node) !== undefined;
+        default:
+            return false;
+    }
+};
+/**
+ * Decides a residual through `exists`. A to-one step whose references the row carries
+ * is asked on the row they name, with the row's own values: for a created row, and for
+ * an updated one too, since a caller may ask before the write, when the database still
+ * holds the old reference. Whatever else an existing row leaves is asked about the row
+ * itself, by its identifier (in one question when no step goes by reference); for a
+ * created row it is unknown.
+ */
+const askOn = async (context, resource, node, kind) => {
+    if (kind === "existing" && !stepsByReference(context, resource, node)) {
+        return node.k === "true"
+            ? true
+            : node.k === "false"
+                ? false
+                : askByIdentifier(context, resource, node);
+    }
+    switch (node.k) {
+        case "true":
+            return true;
+        case "false":
+            return false;
+        case "and":
+        case "all": {
+            let unknown = false;
+            for (const arg of node.args) {
+                const answer = await askOn(context, resource, arg, kind);
+                if (answer === false) {
+                    return false;
+                }
+                unknown ||= answer === "unknown";
+            }
+            return unknown ? "unknown" : true;
+        }
+        case "or": {
+            let unknown = false;
+            for (const arg of node.args) {
+                const answer = await askOn(context, resource, arg, kind);
+                if (answer === true) {
+                    return true;
+                }
+                unknown ||= answer === "unknown";
+            }
+            return unknown ? "unknown" : false;
+        }
+        case "not": {
+            const answer = await askOn(context, resource, node.arg, kind);
+            return answer === "unknown" ? "unknown" : !answer;
+        }
+        case "rel": {
+            const carried = carriedReferences(context, resource, node);
+            if (carried === undefined) {
+                return kind === "existing"
+                    ? askByIdentifier(context, resource, node)
+                    : "unknown";
+            }
+            if (carried.values.some((value) => value === null)) {
+                return false;
+            }
+            const where = Object.fromEntries(carried.references.map((field, index) => [
+                field,
+                { equals: whereValue(carried.values[index]) },
+            ]));
+            return ask(context, node.target, combine(context.policies, node.target, where, node.where));
+        }
+        default:
+            return kind === "existing"
+                ? askByIdentifier(context, resource, node)
+                : "unknown";
+    }
+};
+/**
+ * Decides a folded condition on a row: in memory first, then through `exists` for
+ * what the row does not carry. `"unknown"` when neither can decide.
+ */
+export const decideOnRow = async (args) => {
+    const residual = evaluateOnRow(args.policies, args.resource, args.condition, args.row);
+    if (residual.k === "true") {
+        return true;
+    }
+    if (residual.k === "false") {
+        return false;
+    }
+    if (residual.k === "unknown") {
+        return "unknown";
+    }
+    const context = {
+        policies: args.policies,
+        row: args.row,
+        exists: args.exists,
+        lookups: args.lookups,
+    };
+    return askOn(context, args.resource, residual, args.kind);
+};

package/dist/random-secret.generator.d.ts

@@ -0,0 +1,2 @@
+/** `prefix` and 256 random bits from the runtime's CSPRNG, in base64url. */
+export declare const randomSecret: (prefix: string) => string;

package/dist/random-secret.generator.js

@@ -0,0 +1,15 @@
+// The secrets Access issues (registry keys, kiosk device secrets, beacons): a
+// prefix that names what the secret is, then 256 random bits from the runtime's
+// CSPRNG in base64url (43 characters, no padding).
+const base64url = (bytes) => {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+};
+/** `prefix` and 256 random bits from the runtime's CSPRNG, in base64url. */
+export const randomSecret = (prefix) => `${prefix}${base64url(crypto.getRandomValues(new Uint8Array(32)))}`;

package/dist/reference-reads.check.d.ts

@@ -0,0 +1,12 @@
+import type { AccessPolicies } from "./policies-contract.js";
+/**
+ * The warnings for `policies` hosted by a framework that holds references to the
+ * Resources in `held`, one per writing role and target Resource, each naming every
+ * reference that role may write to it.
+ */
+export declare const referenceReadWarnings: (policies: AccessPolicies, held: ReadonlySet<string>) => readonly string[];
+/**
+ * Emits `policies`' warnings under a framework that holds references to the
+ * Resources in `held`, each once per process and namespace.
+ */
+export declare const warnReferenceReads: (policies: AccessPolicies, held: ReadonlySet<string>) => void;

package/dist/reference-reads.check.js

@@ -0,0 +1,148 @@
+// A check of the rules against the framework that hosts them: a role that may
+// create or update a row holding a reference (a to-one relation's reference fields)
+// to a Resource no read grant reaches for that role. Aventara holds a reference a
+// write sends to the rows the caller may read, so such a write is refused at run
+// time (A4002) whatever the write grant says. It holds only references to the
+// Resources its Core Contract shows, and the app's root exemptions decide those,
+// which the rules cannot see. So the check runs when the framework hosts the
+// engine: core calls `engine.hosted({ held })` once it is built, `held` being the
+// Resources it holds references to, and only those are warned about. Compiling the
+// rules (`.contract()`, `avaccess push`) and building their engine warn about
+// nothing, and a service that does not run on Aventara (the generated client, the
+// standalone host) holds no reference and is never told.
+//
+// It warns and never refuses: the engine answers exactly as before. The warning is
+// Node.js's (`process.emitWarning`, code ACCESS_REFERENCE_UNREADABLE, silenced
+// with `--disable-warning=ACCESS_REFERENCE_UNREADABLE`), else `console.warn`;
+// each one is emitted once per process and namespace.
+//
+// "Reaches" errs towards silence, since the rules cannot say which roles one
+// caller holds together. A read grant on the target (or on `*`) reaches a role when
+// it names that role, `anyone`, or `signedIn` (for any role but `anyone`). A grant
+// that names the target itself also reaches a `signedIn` writer whatever role it
+// names (the caller may hold it), and reaches a role held on rows of one Resource
+// when it names another role held on that same Resource. A held target the
+// rules' schema does not have is reached by no grant (`*` does not reach it, and a
+// grant cannot name it), so a write to it is warned about for every writer. Not
+// warned about: a reference the grant's `write.except` locks (its relation or a
+// reference field; the write is refused for the field itself), a target the
+// framework does not hold, a target the rules read as foreign (the engine lists it
+// in `unheld`, so the framework holds no reference to it; the write grant decides
+// which row may be linked, foreign-references.check.ts), and a writing Resource it
+// does not serve (`held` is its Core Contract's Resources, and no write reaches one
+// outside it).
+import { emitAccessWarning } from "./access-warning.emitter.js";
+import { ownOf } from "./scope.resolver.js";
+const WARNING_CODE = "ACCESS_REFERENCE_UNREADABLE";
+/** The Resource a row role is held on, or `undefined` for `signedIn`, `anyone` and a global role. */
+const heldOn = (policies, role) => {
+    const definition = ownOf(policies.roles, role);
+    return definition !== undefined && "on" in definition
+        ? definition.on
+        : undefined;
+};
+const reaches = (policies, read, writer, target) => read.subjects.some((subject) => {
+    if (subject === writer ||
+        subject === "anyone" ||
+        (subject === "signedIn" && writer !== "anyone")) {
+        return true;
+    }
+    if (read.resource !== target) {
+        return false;
+    }
+    if (writer === "signedIn") {
+        return true;
+    }
+    const on = heldOn(policies, writer);
+    return on !== undefined && heldOn(policies, subject) === on;
+});
+const listed = (names) => names.length < 2
+    ? names.join("")
+    : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+/**
+ * The warnings for `policies` hosted by a framework that holds references to the
+ * Resources in `held`, one per writing role and target Resource, each naming every
+ * reference that role may write to it.
+ */
+export const referenceReadWarnings = (policies, held) => {
+    const reads = policies.grants.filter((grant) => grant.actions.includes("read"));
+    const found = new Map();
+    for (const grant of policies.grants) {
+        if (!grant.actions.some((a) => a === "create" || a === "update")) {
+            continue;
+        }
+        const locked = new Set(grant.write?.except ?? []);
+        const resources = grant.resource === "*" ? Object.keys(policies.schema) : [grant.resource];
+        for (const resource of resources) {
+            const facts = ownOf(policies.schema, resource);
+            // A Resource the framework does not serve is never written through it
+            // (its Core Contract has no such Resource, nor a relation to it).
+            if (facts === undefined ||
+                facts.foreign !== undefined ||
+                !held.has(resource)) {
+                continue;
+            }
+            for (const [relation, fact] of Object.entries(facts.relations)) {
+                const fields = fact.referenceFields;
+                const target = ownOf(policies.schema, fact.target);
+                if (fact.cardinality !== "one" ||
+                    fields === undefined ||
+                    locked.has(relation) ||
+                    fields.some((field) => locked.has(field))) {
+                    continue;
+                }
+                // A foreign target is never held: the engine lists it in `unheld`.
+                if (!held.has(fact.target) || target?.foreign !== undefined) {
+                    continue;
+                }
+                // A target the schema does not have takes no grant: `*` does not
+                // reach it (`rulesFor`), and a grant cannot name it.
+                const own = target !== undefined;
+                const readsOfTarget = own
+                    ? reads.filter((read) => read.resource === fact.target || read.resource === "*")
+                    : [];
+                for (const writer of grant.subjects) {
+                    if (readsOfTarget.some((read) => reaches(policies, read, writer, fact.target))) {
+                        continue;
+                    }
+                    const key = `${writer}\u0000${fact.target}`;
+                    const entry = found.get(key) ?? {
+                        writer,
+                        target: fact.target,
+                        own,
+                        references: [],
+                    };
+                    for (const field of fields) {
+                        const name = `${resource}.${field}`;
+                        if (!entry.references.includes(name)) {
+                            entry.references.push(name);
+                        }
+                    }
+                    found.set(key, entry);
+                }
+            }
+        }
+    }
+    return [...found.values()].map(({ writer, target, own, references }) => {
+        const one = references.length === 1;
+        const what = `${writer} may write ${listed(references)}, ${one ? "a reference" : "references"} to Resource "${target}"`;
+        const hold = "Aventara holds a reference a write sends to the rows the caller may read, so these writes are refused (A4002).";
+        const out = "the reference out of the write (`write: { except: [...] }`).";
+        if (!own) {
+            return `${what}, which the rules' schema does not have: no read grant in these rules reaches it, and none can. ${hold} Leave ${out}`;
+        }
+        const to = writer === "signedIn" || writer === "anyone"
+            ? writer
+            : `${writer} (or to signedIn)`;
+        return `${what}, but no read grant on "${target}" reaches ${writer}. ${hold} Grant read on "${target}" to ${to}, or leave ${out}`;
+    });
+};
+/**
+ * Emits `policies`' warnings under a framework that holds references to the
+ * Resources in `held`, each once per process and namespace.
+ */
+export const warnReferenceReads = (policies, held) => {
+    for (const message of referenceReadWarnings(policies, held)) {
+        emitAccessWarning(WARNING_CODE, policies.namespace, message);
+    }
+};