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

package/dist/generator/prisma7/prisma-schema.reader.d.ts

@@ -0,0 +1,9 @@
+import type { AccessSchema } from "../../access-schema.js";
+/** What the reader made of a schema: the `AccessSchema`, and what it left out and why. */
+type PrismaSchemaReading = {
+    readonly schema: AccessSchema;
+    readonly skipped: readonly string[];
+};
+/** Reads the Prisma schema at `path` (a `.prisma` file or a folder of them) as an `AccessSchema`. */
+export declare const readPrismaSchema: (path: string) => Promise<PrismaSchemaReading>;
+export {};

package/dist/generator/prisma7/prisma-schema.reader.js

@@ -0,0 +1,394 @@
+// A Prisma 7 schema (`schema.prisma`, or a folder of `.prisma` files) read as the
+// `AccessSchema` a service authors its rules against with `definePolicies`. It reads
+// what the Aventara framework's Prisma 7 discovery reads for the same facts, so an
+// Aventara app's discovered model and this reader agree on every Resource: each
+// model's scalar and relation fields, enums, the reference pairs a relation holds,
+// its inverse, and the field tuples that identify a row.
+//
+// It is a bounded reader, not a parser: Prisma's schema language puts each field and
+// each block attribute on one line of its own (a declaration split over lines is a
+// Prisma validation error), so it reads line by line. It locates tokens and never
+// evaluates them: `@default(...)`, `@map`, `@db.*`, `@@index` and `@@schema` are
+// read past. What it cannot model (an `Unsupported(...)` column, a composite `type`,
+// a `view`, an `@ignore`d field or model) is left out and reported, never guessed.
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { BEACON_TABLE } from "../../beacon/beacon.store.js";
+/** Prisma's built-in scalars, as Access (and the framework) name them. */
+const SCALARS = {
+    String: "string",
+    Boolean: "boolean",
+    Int: "int",
+    Float: "float",
+    BigInt: "bigint",
+    Decimal: "decimal",
+    DateTime: "datetime",
+    Bytes: "bytes",
+    Json: "json",
+};
+/** A line without its comment: `//` outside a string literal ends the line. */
+const withoutComment = (line) => {
+    let quoted = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (char === "\\" && quoted) {
+            index += 1;
+        }
+        else if (char === '"') {
+            quoted = !quoted;
+        }
+        else if (!quoted && char === "/" && line[index + 1] === "/") {
+            return line.slice(0, index);
+        }
+    }
+    return line;
+};
+/** The `@name(args)` and `@@name(args)` attributes of a line, in order, with their raw arguments. */
+const attributesOf = (text) => {
+    const attributes = [];
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== "@") {
+            index += 1;
+            continue;
+        }
+        const start = index;
+        while (text[index] === "@") {
+            index += 1;
+        }
+        const nameMatch = /^[A-Za-z_][\w.]*/.exec(text.slice(index));
+        const name = `${text.slice(start, index)}${nameMatch?.[0] ?? ""}`;
+        index += nameMatch?.[0].length ?? 0;
+        let args;
+        if (text[index] === "(") {
+            let depth = 0;
+            let quoted = false;
+            const open = index;
+            for (; index < text.length; index += 1) {
+                const char = text[index];
+                if (quoted) {
+                    if (char === "\\") {
+                        index += 1;
+                    }
+                    else if (char === '"') {
+                        quoted = false;
+                    }
+                }
+                else if (char === '"') {
+                    quoted = true;
+                }
+                else if (char === "(") {
+                    depth += 1;
+                }
+                else if (char === ")") {
+                    depth -= 1;
+                    if (depth === 0) {
+                        index += 1;
+                        break;
+                    }
+                }
+            }
+            args = text.slice(open + 1, index - 1);
+        }
+        attributes.push({ name, args });
+    }
+    return attributes;
+};
+/** An attribute's arguments split at the commas outside brackets, parentheses and strings. */
+const argumentsOf = (args) => {
+    const parts = [];
+    let depth = 0;
+    let quoted = false;
+    let current = "";
+    for (let index = 0; index < args.length; index += 1) {
+        const char = args[index] ?? "";
+        if (quoted) {
+            current += char;
+            if (char === "\\") {
+                current += args[index + 1] ?? "";
+                index += 1;
+            }
+            else if (char === '"') {
+                quoted = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            quoted = true;
+        }
+        else if (char === "(" || char === "[") {
+            depth += 1;
+        }
+        else if (char === ")" || char === "]") {
+            depth -= 1;
+        }
+        else if (char === "," && depth === 0) {
+            parts.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim() !== "") {
+        parts.push(current.trim());
+    }
+    return parts;
+};
+/** The named argument `name:` of an attribute, or its first positional one when `name` is `undefined`. */
+const argumentOf = (args, name) => {
+    for (const part of argumentsOf(args ?? "")) {
+        const named = /^([A-Za-z_]\w*)\s*:\s*([\s\S]*)$/.exec(part);
+        if (name === undefined ? named === null : named?.[1] === name) {
+            return name === undefined ? part : named?.[2]?.trim();
+        }
+    }
+    return undefined;
+};
+/** The field names of a `[a, b(sort: Desc)]` list. */
+const fieldListOf = (list) => {
+    const inner = /^\[([\s\S]*)\]$/.exec(list?.trim() ?? "")?.[1];
+    if (inner === undefined) {
+        return undefined;
+    }
+    return argumentsOf(inner)
+        .map((member) => /^[A-Za-z_]\w*/.exec(member)?.[0] ?? "")
+        .filter((member) => member !== "");
+};
+/** A string literal's value: `"Mentorship"` → `Mentorship`. */
+const stringOf = (literal) => /^"((?:[^"\\]|\\.)*)"$/.exec(literal?.trim() ?? "")?.[1];
+const FIELD = /^([A-Za-z_]\w*)\s+([A-Za-z_]\w*(?:\([^)]*\))?)(\[\])?(\?)?(.*)$/;
+/** The `.prisma` files at `path`: the file itself, or every one under the folder, by path. */
+const schemaFiles = async (path) => {
+    if (path.endsWith(".prisma")) {
+        return [path];
+    }
+    const files = [];
+    const walk = async (folder) => {
+        const entries = await readdir(folder, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = resolve(folder, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".prisma")) {
+                files.push(full);
+            }
+        }
+    };
+    await walk(path);
+    return files.sort();
+};
+/** Reads the schema's blocks: models with their lines, enums with their values. */
+const blocksOf = (sources, skipped) => {
+    const models = [];
+    const enums = new Map();
+    const composites = new Set();
+    for (const { file, text } of sources) {
+        let block;
+        for (const raw of text.split(/\r?\n/)) {
+            const line = withoutComment(raw).trim();
+            if (line === "") {
+                continue;
+            }
+            if (block === undefined) {
+                const opened = /^(\w+)\s+([A-Za-z_]\w*)\s*\{$/.exec(line);
+                if (opened !== null) {
+                    block = { kind: opened[1] ?? "", name: opened[2] ?? "", lines: [] };
+                }
+                continue;
+            }
+            if (line === "}") {
+                if (block.kind === "model") {
+                    const fields = [];
+                    const blockAttributes = [];
+                    for (const member of block.lines) {
+                        if (member.startsWith("@@")) {
+                            blockAttributes.push(...attributesOf(member));
+                            continue;
+                        }
+                        const field = FIELD.exec(member);
+                        if (field === null) {
+                            continue;
+                        }
+                        fields.push({
+                            name: field[1] ?? "",
+                            type: field[2] ?? "",
+                            list: field[3] !== undefined,
+                            optional: field[4] !== undefined,
+                            attributes: attributesOf(field[5] ?? ""),
+                        });
+                    }
+                    models.push({ name: block.name, file, fields, blockAttributes });
+                }
+                else if (block.kind === "enum") {
+                    enums.set(block.name, block.lines
+                        .filter((member) => !member.startsWith("@@"))
+                        .map((member) => /^[A-Za-z_]\w*/.exec(member)?.[0] ?? "")
+                        .filter((member) => member !== ""));
+                }
+                else if (block.kind === "type") {
+                    composites.add(block.name);
+                }
+                else if (block.kind === "view") {
+                    skipped.push(`view ${block.name}: a view is not a Resource Access reads; left out`);
+                }
+                block = undefined;
+                continue;
+            }
+            block.lines.push(line);
+        }
+    }
+    return { models, enums, composites };
+};
+const has = (attributes, name) => attributes.some((attribute) => attribute.name === name);
+/** The relation's name, from `@relation("Name")` or `@relation(name: "Name")`. */
+const relationNameOf = (field) => {
+    const relation = field.attributes.find((attribute) => attribute.name === "@relation");
+    if (relation === undefined) {
+        return null;
+    }
+    return (stringOf(argumentOf(relation.args, "name")) ??
+        stringOf(argumentOf(relation.args, undefined)) ??
+        null);
+};
+/** Whether a model is the ownership beacon's table: named, or mapped to, `_aventara_beacon`. */
+const isBeaconTable = (model) => BEACON_NAMES.includes(model.name) ||
+    model.blockAttributes.some((attribute) => attribute.name === "@@map" &&
+        BEACON_NAMES.includes(stringOf(argumentOf(attribute.args, undefined) ??
+            argumentOf(attribute.args, "name")) ?? ""));
+/** The beacon table's names: a service's `_aventara_beacon`, the Access server's `aventaraBeacon` (Prisma model `AventaraBeacon`). */
+const BEACON_NAMES = [
+    BEACON_TABLE,
+    "aventaraBeacon",
+    "AventaraBeacon",
+];
+/** Reads the Prisma schema at `path` (a `.prisma` file or a folder of them) as an `AccessSchema`. */
+export const readPrismaSchema = async (path) => {
+    const sources = await Promise.all((await schemaFiles(path)).map(async (file) => ({
+        file,
+        text: await readFile(file, "utf8"),
+    })));
+    const skipped = [];
+    const { models: declared, enums, composites } = blocksOf(sources, skipped);
+    const models = declared.filter((model) => {
+        if (has(model.blockAttributes, "@@ignore")) {
+            skipped.push(`model ${model.name}: @@ignore; left out`);
+            return false;
+        }
+        if (isBeaconTable(model)) {
+            skipped.push(`model ${model.name}: the ownership beacon's table, which no rule reads; left out`);
+            return false;
+        }
+        return true;
+    });
+    const byName = new Map(models.map((model) => [model.name, model]));
+    const ignoredModels = new Set(declared.filter((model) => !byName.has(model.name)).map((m) => m.name));
+    const resources = {};
+    for (const model of models) {
+        const fields = {};
+        const columns = new Map();
+        for (const field of model.fields) {
+            const where = `${model.name}.${field.name}`;
+            if (has(field.attributes, "@ignore")) {
+                skipped.push(`${where}: @ignore; left out`);
+                continue;
+            }
+            const scalar = SCALARS[field.type];
+            if (scalar !== undefined || enums.has(field.type)) {
+                fields[field.name] = {
+                    kind: "scalar",
+                    type: scalar !== undefined ? { scalar } : { enum: field.type },
+                    nullable: field.optional,
+                    list: field.list,
+                };
+                if (!field.list) {
+                    columns.set(field.name, field);
+                }
+                continue;
+            }
+            const target = byName.get(field.type);
+            if (target === undefined) {
+                skipped.push(`${where}: ${field.type.startsWith("Unsupported(")
+                    ? "an Unsupported column"
+                    : composites.has(field.type)
+                        ? `the composite type ${field.type}`
+                        : ignoredModels.has(field.type)
+                            ? `a relation to the ignored model ${field.type}`
+                            : `the type ${field.type}, which the schema does not declare`}; left out`);
+                continue;
+            }
+            const name = relationNameOf(field);
+            const partners = target.fields.filter((candidate) => candidate.type === model.name &&
+                relationNameOf(candidate) === name &&
+                !(target.name === model.name && candidate.name === field.name));
+            const relation = field.attributes.find((attribute) => attribute.name === "@relation");
+            const referenceFields = fieldListOf(argumentOf(relation?.args, "fields"));
+            const references = fieldListOf(argumentOf(relation?.args, "references"));
+            const cardinality = field.list ? "many" : "one";
+            const fact = {
+                kind: "relation",
+                target: target.name,
+                cardinality,
+                nullable: cardinality === "one" && field.optional,
+                ...(partners.length === 1 && partners[0] !== undefined
+                    ? { inverse: partners[0].name }
+                    : {}),
+                ...(referenceFields !== undefined &&
+                    referenceFields.length > 0 &&
+                    references !== undefined &&
+                    references.length > 0
+                    ? {
+                        referenceFields: referenceFields,
+                        references: references,
+                    }
+                    : {}),
+            };
+            fields[field.name] = fact;
+        }
+        // Identifiers, as discovery lists them: each field's `@id` then `@unique`, in
+        // field order, then `@@id`, then each `@@unique`; a tuple once; none over a
+        // field that is not a column here, and none over a nullable one.
+        const criteria = [];
+        for (const field of model.fields) {
+            if (has(field.attributes, "@id")) {
+                criteria.push([field.name]);
+            }
+            if (has(field.attributes, "@unique")) {
+                criteria.push([field.name]);
+            }
+        }
+        for (const name of ["@@id", "@@unique"]) {
+            for (const attribute of model.blockAttributes) {
+                if (attribute.name !== name) {
+                    continue;
+                }
+                const members = fieldListOf(argumentOf(attribute.args, "fields")) ??
+                    fieldListOf(argumentOf(attribute.args, undefined));
+                if (members !== undefined) {
+                    criteria.push(members);
+                }
+            }
+        }
+        const seen = new Set();
+        const identifiers = [];
+        for (const members of criteria) {
+            const key = JSON.stringify(members);
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            if (members.length > 0 &&
+                members.every((member) => columns.get(member)?.optional === false)) {
+                identifiers.push(members);
+            }
+        }
+        resources[model.name] = { fields, identifiers };
+    }
+    return {
+        schema: {
+            enums: Object.fromEntries([...enums].map(([name, values]) => [name, { values }])),
+            resources,
+        },
+        skipped,
+    };
+};

package/dist/generator/prisma7/prisma-where.translator.d.ts

@@ -0,0 +1,72 @@
+import { type AccessWhere } from "../../aventara-where.translator.js";
+import type { AccessFields } from "../../policies.decider.js";
+import type { AccessPolicies } from "../../policies-contract.js";
+/** A Prisma `where`: plain data any `<Model>WhereInput` accepts. */
+export type PrismaWhere = {
+    [key: string]: unknown;
+};
+/** A Prisma `select` of scalar fields. */
+export type PrismaSelect = {
+    [field: string]: true;
+};
+/** What `prismaExists` needs of a model's delegate on the Prisma client. */
+export type PrismaFindFirst = {
+    findFirst(args: {
+        where: PrismaWhere;
+        select: PrismaSelect;
+    }): PromiseLike<unknown>;
+};
+/** Aventara's `where` on a Resource of `policies`, as Prisma's `where` on its model. */
+export declare const toPrismaWhere: (policies: AccessPolicies, resource: string, where: AccessWhere) => PrismaWhere;
+/**
+ * A scope (`scopeOf`'s answer) as Prisma's `where`: every row (`{}`), no row
+ * (`{ OR: [] }`, which Prisma matches with nothing), or the translated condition.
+ */
+export declare const toPrismaScope: (policies: AccessPolicies, resource: string, scope: boolean | AccessWhere) => PrismaWhere;
+/**
+ * A `fieldsOf` read answer as Prisma's `select`: the Resource's scalar fields a read
+ * shows on every row. A governed field is selected only when the answer opens it on
+ * every row; a field it opens on some rows only is left out, since a `select` cannot
+ * depend on the row (ask `fieldsOf` for those). Relations are never selected: a
+ * related row would not be scoped.
+ */
+export declare const toPrismaSelect: (policies: AccessPolicies, resource: string, fields: AccessFields) => PrismaSelect;
+/** The property of the Prisma client that holds a model's delegate: its name, first letter lowered. */
+export declare const prismaDelegateOf: (resource: string) => string;
+/**
+ * Core's `exists`, through the service's Prisma client: whether a row of `resource`
+ * meets `where`, unscoped. It selects the row's first identifier and nothing else.
+ */
+export declare const existsThroughPrisma: (client: object, policies: AccessPolicies, resource: string, where: AccessWhere) => Promise<boolean>;
+/**
+ * The Prisma client the ownership beacon is read and written through: a model over
+ * the `_aventara_beacon` table, keyed by the namespace,
+ * `model AventaraBeacon { id String @id  namespace String @unique  value String  createdAt DateTime @default(now())  @@map("_aventara_beacon") }`.
+ */
+export type PrismaBeaconClient = {
+    readonly aventaraBeacon: {
+        findUnique(args: {
+            where: {
+                namespace: string;
+            };
+            select: {
+                value: true;
+            };
+        }): PromiseLike<unknown>;
+        create(args: {
+            data: {
+                namespace: string;
+                value: string;
+            };
+        }): PromiseLike<unknown>;
+    };
+};
+/**
+ * The beacon store over the service's Prisma client: `read` a namespace's row in
+ * `_aventara_beacon`, `create` one. What `avaccess push --beacon` and `pull --beacon`
+ * load, and what the client's `checkBeacons` reads through.
+ */
+export declare const beaconThroughPrisma: (client: PrismaBeaconClient) => {
+    read(namespace: string): Promise<string | null>;
+    create(namespace: string, value: string): Promise<void>;
+};

package/dist/generator/prisma7/prisma-where.translator.js

@@ -0,0 +1,136 @@
+// The Prisma 7 translator: the answers the decisions give, in Prisma's words. A scope
+// (`scopeOf`'s `where`, the shape the engine hands Aventara) becomes a Prisma
+// `where`, a `fieldsOf` read answer becomes a Prisma `select`, and an `exists`
+// question is asked through the service's own Prisma client. `avaccess generate
+// --orm prisma7` copies this module into the generated client beside the decisions;
+// like them, it imports nothing but them, and no Prisma module: what it builds is
+// plain data that Prisma's own input types accept.
+//
+// Each step mirrors how the framework's Prisma 7 adapter writes Aventara's `where`:
+// boolean nodes (`AND`, `OR`, `NOT`) and the scalar operators (`equals`, `not`,
+// `in`, `notIn`) keep their spelling; a to-one relation's condition is wrapped in
+// Prisma's `is`, because Prisma reads an empty unwrapped one as no condition at all;
+// a to-many relation's `some`, `every` and `none` keep theirs.
+import { defineMember, } from "../../aventara-where.translator.js";
+const isWhereNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A record's own member, never one it inherits. */
+const own = (record, key) => record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
+/**
+ * A scalar field's operators, with each `in` list copied (Prisma's lists are
+ * mutable). A bigint past a safe integer, which the file writes as its digits, is
+ * handed to Prisma as a `bigint`.
+ */
+const operatorsOf = (value, bigint) => {
+    const operandOf = (operand) => bigint && typeof operand === "string" ? BigInt(operand) : operand;
+    return isWhereNode(value)
+        ? Object.fromEntries(Object.entries(value).map(([operator, operand]) => [
+            operator,
+            Array.isArray(operand) ? operand.map(operandOf) : operandOf(operand),
+        ]))
+        : value;
+};
+/** Aventara's `where` on a Resource of `policies`, as Prisma's `where` on its model. */
+export const toPrismaWhere = (policies, resource, where) => {
+    const facts = own(policies.schema, resource);
+    const relations = facts?.relations ?? {};
+    const translated = {};
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "AND" || key === "OR") {
+            defineMember(translated, key, value.map((node) => toPrismaWhere(policies, resource, node)));
+            continue;
+        }
+        if (key === "NOT") {
+            defineMember(translated, key, toPrismaWhere(policies, resource, value));
+            continue;
+        }
+        const relation = own(relations, key);
+        if (relation === undefined || !isWhereNode(value)) {
+            defineMember(translated, key, operatorsOf(value, own(facts?.types, key) === "bigint"));
+            continue;
+        }
+        if (relation.cardinality === "one") {
+            defineMember(translated, key, {
+                is: toPrismaWhere(policies, relation.target, value),
+            });
+            continue;
+        }
+        defineMember(translated, key, Object.fromEntries(Object.entries(value).map(([quantifier, node]) => [
+            quantifier,
+            toPrismaWhere(policies, relation.target, node),
+        ])));
+    }
+    return translated;
+};
+/**
+ * A scope (`scopeOf`'s answer) as Prisma's `where`: every row (`{}`), no row
+ * (`{ OR: [] }`, which Prisma matches with nothing), or the translated condition.
+ */
+export const toPrismaScope = (policies, resource, scope) => scope === true
+    ? {}
+    : scope === false
+        ? { OR: [] }
+        : toPrismaWhere(policies, resource, scope);
+/**
+ * A `fieldsOf` read answer as Prisma's `select`: the Resource's scalar fields a read
+ * shows on every row. A governed field is selected only when the answer opens it on
+ * every row; a field it opens on some rows only is left out, since a `select` cannot
+ * depend on the row (ask `fieldsOf` for those). Relations are never selected: a
+ * related row would not be scoped.
+ */
+export const toPrismaSelect = (policies, resource, fields) => {
+    const facts = own(policies.schema, resource);
+    const governed = own(policies.govern, resource) ?? [];
+    const scalars = (facts?.fields ?? []).filter((field) => own(facts?.relations, field) === undefined);
+    const select = {};
+    for (const field of scalars) {
+        const opened = own(fields.perRow, field);
+        const everyRow = opened !== undefined && Object.keys(opened).length === 0;
+        const always = !governed.includes(field) &&
+            (fields.always === "all" || fields.always.includes(field));
+        if (always || everyRow) {
+            select[field] = true;
+        }
+    }
+    return select;
+};
+/** The property of the Prisma client that holds a model's delegate: its name, first letter lowered. */
+export const prismaDelegateOf = (resource) => `${resource.charAt(0).toLowerCase()}${resource.slice(1)}`;
+/**
+ * Core's `exists`, through the service's Prisma client: whether a row of `resource`
+ * meets `where`, unscoped. It selects the row's first identifier and nothing else.
+ */
+export const existsThroughPrisma = async (client, policies, resource, where) => {
+    const delegateName = prismaDelegateOf(resource);
+    const delegate = client[delegateName];
+    if (delegate === undefined || typeof delegate.findFirst !== "function") {
+        throw new Error(`Aventara Access: the rules ask whether a ${resource} row exists, and the Prisma client has no \`${delegateName}\`: add the model ${resource} to the Prisma schema this service queries`);
+    }
+    const facts = own(policies.schema, resource);
+    const identifier = facts?.identifiers[0] ?? facts?.fields.slice(0, 1) ?? [];
+    const select = {};
+    for (const field of identifier) {
+        select[field] = true;
+    }
+    const found = await delegate.findFirst({
+        where: toPrismaWhere(policies, resource, where),
+        select,
+    });
+    return found !== null && found !== undefined;
+};
+/**
+ * The beacon store over the service's Prisma client: `read` a namespace's row in
+ * `_aventara_beacon`, `create` one. What `avaccess push --beacon` and `pull --beacon`
+ * load, and what the client's `checkBeacons` reads through.
+ */
+export const beaconThroughPrisma = (client) => ({
+    read: async (namespace) => {
+        const row = (await client.aventaraBeacon.findUnique({
+            where: { namespace },
+            select: { value: true },
+        }));
+        return typeof row?.value === "string" ? row.value : null;
+    },
+    create: async (namespace, value) => {
+        await client.aventaraBeacon.create({ data: { namespace, value } });
+    },
+});

package/dist/generator/prisma7/prisma7.translator.d.ts

@@ -0,0 +1,2 @@
+import type { OrmTranslator } from "../orm.translator.js";
+export declare const prisma7Translator: OrmTranslator;