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

package/dist/generator/prisma7/prisma7.translator.js

@@ -0,0 +1,87 @@
+// The Prisma 7 translator (`--orm prisma7`). In a generated client it adds
+// `prismaWhere` (a scope as a Prisma `where`), `readable` (a read's fields as a
+// Prisma `select`), `prismaExists` (`can`'s `exists`, through the service's Prisma
+// client) and `prismaBeacon` (the ownership beacon's store over a Prisma model of
+// `_aventara_beacon`), typed by the namespace's Resources, over the copied
+// `prisma-where.translator.ts`. For `avaccess schema` it reads `schema.prisma`.
+// Neither imports a Prisma module: the generated client stays free of any import.
+import { propertyKey } from "../namespace.facts.js";
+import { readPrismaSchema } from "./prisma-schema.reader.js";
+import { prismaDelegateOf } from "./prisma-where.translator.js";
+const clientPart = (namespace) => {
+    const delegates = namespace.resources.map((resource) => `\treadonly ${propertyKey(prismaDelegateOf(resource.name))}${resource.foreign === undefined ? "" : "?"}: PrismaFindFirst;`);
+    const text = `/**
+ * The Prisma client \`prismaExists\` asks through: a model delegate per Resource the
+ * rules name (a foreign one only when this service's schema maps it).
+ */
+export type PrismaClientOf = {
+${delegates.join("\n")}
+};
+
+/** A Prisma \`select\` of the scalar fields of \`R\`. */
+export type PrismaSelectOf<R extends ResourceName> = {
+	[F in ResourceFields[R]]?: true;
+};
+
+/** A scope (\`scopeOf\`'s answer) on \`resource\` as a Prisma \`where\`: \`true\` every row, \`false\` none. */
+const prismaWhere = (
+	resource: ResourceName,
+	scope: boolean | AccessWhere,
+): PrismaWhere => toPrismaScope(policies, resource, scope);
+
+/**
+ * The fields a read shows on every row, as a Prisma \`select\`. A governed field that
+ * a grant opens on some rows only is left out (ask \`fieldsOf\` for it); no relation
+ * is selected, since a related row would not be scoped.
+ */
+const readable = <R extends ResourceName>(
+	question: QuestionOf<R>,
+): PrismaSelectOf<R> =>
+	toPrismaSelect(
+		policies,
+		question.resource,
+		decider.fieldsOf({ ...question, access: "read" }),
+	) as PrismaSelectOf<R>;
+
+/**
+ * \`can\`'s \`exists\`, through your Prisma client:
+ * \`exists: (resource, where) => access.prismaExists(prisma, resource, where)\`.
+ */
+const prismaExists = (
+	prisma: PrismaClientOf,
+	resource: ResourceName,
+	where: AccessWhere,
+): Promise<boolean> => existsThroughPrisma(prisma, policies, resource, where);
+
+/**
+ * The ownership beacon's store over your Prisma client (the \`AventaraBeacon\` model
+ * over the beacon table, see \`PrismaBeaconClient\`): what \`avaccess push --beacon\`
+ * and \`avaccess pull --beacon\` load, and what
+ * \`access.checkBeacons(access.prismaBeacon(prisma), pins, environment)\` reads at
+ * startup, \`pins\` being this environment's avAccess.beacons.<environment>.json.
+ */
+const prismaBeacon = (prisma: PrismaBeaconClient) => beaconThroughPrisma(prisma);
+`;
+    return {
+        text,
+        members: ["prismaWhere", "readable", "prismaExists", "prismaBeacon"],
+        imports: {
+            values: [
+                "beaconThroughPrisma",
+                "existsThroughPrisma",
+                "toPrismaScope",
+                "toPrismaSelect",
+            ],
+            types: ["PrismaBeaconClient", "PrismaFindFirst", "PrismaWhere"],
+        },
+        exports: ["PrismaBeaconClient", "PrismaWhere"],
+    };
+};
+export const prisma7Translator = {
+    orm: "prisma7",
+    title: "Prisma 7",
+    modules: ["src/generator/prisma7/prisma-where.translator.ts"],
+    clientPart,
+    defaultSchema: "prisma/schema.prisma",
+    readSchema: readPrismaSchema,
+};

package/dist/generator/schema.emitter.d.ts

@@ -0,0 +1,14 @@
+import type { AccessSchema } from "../access-schema.js";
+import type { OrmTranslator } from "./orm.translator.js";
+/** What a schema module is made from. */
+type SchemaModuleInput = {
+    readonly schema: AccessSchema;
+    readonly translator: OrmTranslator;
+    /** The ORM schema it was read from, as the command named it. */
+    readonly source: string;
+    /** The command that regenerates the module, as the banner prints it. */
+    readonly command: string;
+};
+/** The schema module's text. */
+export declare const emitSchemaModule: (input: SchemaModuleInput) => string;
+export {};

package/dist/generator/schema.emitter.js

@@ -0,0 +1,23 @@
+// `avaccess schema`'s output: the `AccessSchema` read from the service's ORM schema,
+// as a TypeScript module a service that does not run on Aventara authors its rules
+// against: `definePolicies(model, { namespace })`, as an Aventara app does with its
+// discovered model. `as const` keeps every name literal, so each rule's Resource,
+// field, relation and enum value is checked at its key. The text is a function of the
+// ORM schema alone.
+import { typescriptLiteral } from "./typescript-literal.writer.js";
+/** The schema module's text. */
+export const emitSchemaModule = (input) => `// biome-ignore-all format: generated output
+// biome-ignore-all lint: generated output
+/* eslint-disable */
+// Generated by \`avaccess schema\` from ${input.source} (${input.translator.title}). Do not edit
+// this file: regenerate it with
+//
+//     ${input.command}
+//
+// when the schema changes. Author the namespace's rules against it:
+//
+//     definePolicies(model, { namespace: "<your namespace>" })
+
+/** The Resources of ${input.source}, their fields and the field tuples that identify a row. */
+export const model = ${typescriptLiteral(input.schema)} as const;
+`;

package/dist/generator/tsconfig.reader.d.ts

@@ -0,0 +1,44 @@
+/** The extension a relative import in the generated client is written with. */
+type ImportExtension = "" | ".js" | ".ts";
+/** Why the project's tsconfig cannot be followed: the sentence the CLI prints. */
+export declare class TsconfigRefusal extends Error {
+}
+/** A tsconfig as `get-tsconfig` resolves it (`TsConfigJsonResolved`): the parts this reads. */
+type ResolvedTsconfig = {
+    compilerOptions?: {
+        [option: string]: unknown;
+    };
+    references?: {
+        path: string;
+    }[];
+    files?: string[];
+    include?: string[];
+    exclude?: string[];
+};
+/** A tsconfig file and its resolved content (`TsConfigResult`). */
+type LocatedTsconfig = {
+    path: string;
+    config: ResolvedTsconfig;
+};
+/** What `createFilesMatcher` is handed: the file lists it matches with, the rest riding along. */
+type MatchedTsconfig = {
+    path: string;
+    config: {
+        files?: string[];
+        include?: string[];
+        exclude?: string[];
+    };
+};
+/** The three calls of `get-tsconfig` this makes, as `avclient` makes them. */
+export type TsconfigLibrary = {
+    getTsconfig: (searchPath?: string) => LocatedTsconfig | null;
+    parseTsconfig: (tsconfigPath: string) => ResolvedTsconfig;
+    createFilesMatcher: (tsconfig: MatchedTsconfig) => (filePath: string) => ResolvedTsconfig | undefined;
+};
+/**
+ * The import extension for the generated client at `file` (absolute), in the project
+ * at `cwd`, from the tsconfig `named` (`--tsconfig`, relative to `cwd`) or found.
+ * Throws a `TsconfigRefusal` when there is none to follow.
+ */
+export declare const importExtensionOf: (cwd: string, file: string, named: string | undefined) => Promise<ImportExtension>;
+export {};

package/dist/generator/tsconfig.reader.js

@@ -0,0 +1,110 @@
+// How the generated client's two files name each other: the extension of the one
+// relative import `avAccess.ts` writes, read from the project's `tsconfig.json` by
+// Prisma 7's `prisma-client` rules, as the framework's `avclient` reads them:
+//
+//   1. `allowImportingTsExtensions` or `rewriteRelativeImportExtensions` → `.ts`;
+//   2. `module` is `commonjs`, or `moduleResolution` is `bundler` (either case)
+//      → no extension;
+//   3. otherwise → `.js` (what Node's ES module resolution, `node16`/`nodenext`,
+//      needs).
+//
+// Which tsconfig, found as `avclient` finds it, with the library and version Prisma 7
+// and `avclient` use (`get-tsconfig`, loaded only when `generate` runs): the one
+// `--tsconfig` names, used as named; otherwise `getTsconfig` from the generated
+// file's directory up, its `extends` chain merged as TypeScript merges it. A
+// solution-style root (Vite's: `"files": []` and `references`) compiles nothing
+// itself: when the config found does not include the generated file and has
+// `references`, the first referenced project that does include it is used, as
+// TypeScript's language service picks a file's project; with none, the root stays.
+//
+// No tsconfig is refused (ruled 2026-10-23, as `avclient` refuses it): the client is
+// TypeScript, compiled by the project's own toolchain the way its tsconfig says, and
+// a project without one is a JavaScript project, not supported yet.
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+/** Why the project's tsconfig cannot be followed: the sentence the CLI prints. */
+export class TsconfigRefusal extends Error {
+}
+/**
+ * Whether `tsconfig` compiles `file`. `parseTsconfig` (4.10.0) turns a
+ * `${configDir}` entry of `files`, `include` or `exclude` into an absolute path, which
+ * `createFilesMatcher` then joins under the config's directory again and never
+ * matches; such an entry is handed to it relative to that directory.
+ */
+const compiles = (library, tsconfig, file) => {
+    const directory = dirname(tsconfig.path);
+    const local = (list) => list?.map((entry) => isAbsolute(entry) ? relative(directory, entry) || "." : entry);
+    const files = local(tsconfig.config.files);
+    const include = local(tsconfig.config.include);
+    const exclude = local(tsconfig.config.exclude);
+    const config = {
+        ...tsconfig.config,
+        ...(files === undefined ? {} : { files }),
+        ...(include === undefined ? {} : { include }),
+        ...(exclude === undefined ? {} : { exclude }),
+    };
+    return (library.createFilesMatcher({ path: tsconfig.path, config })(file) !==
+        undefined);
+};
+/** The compiler options a run follows, from the tsconfig `avclient`'s rules pick. */
+const compilerOptionsOf = async (cwd, file, named) => {
+    const library = (await import("get-tsconfig"));
+    const { getTsconfig, parseTsconfig } = library;
+    if (named !== undefined) {
+        const path = resolve(cwd, named);
+        try {
+            // `get-tsconfig` reads leniently: text that is not a tsconfig parses as an
+            // empty one. Reading it first makes a missing or unreadable file a refusal.
+            await readFile(path, "utf8");
+        }
+        catch (error) {
+            const code = error?.code;
+            throw new TsconfigRefusal(`--tsconfig names ${named}, which could not be read (${typeof code === "string" ? code : String(error)}); it must name the tsconfig.json your project compiles the generated client with. Nothing was written.`);
+        }
+        return parseTsconfig(path).compilerOptions ?? {};
+    }
+    const directory = dirname(file);
+    const found = getTsconfig(directory);
+    if (found === null) {
+        throw new TsconfigRefusal(`no tsconfig.json was found in ${relative(cwd, directory) || "."} or any directory above it. The client avaccess generate writes is TypeScript, compiled by your project's own toolchain and written the way its tsconfig.json says; JavaScript projects are not supported yet. Add a tsconfig.json to the project (\`npx tsc --init\` writes one), or, if it has one this search does not find, name it with \`--tsconfig <file>\`. Nothing was written.`);
+    }
+    const references = found.config.references;
+    if (references === undefined || compiles(library, found, file)) {
+        return found.config.compilerOptions ?? {};
+    }
+    for (const reference of references) {
+        // A config file, or a directory holding `tsconfig.json`; one not there is skipped.
+        const target = resolve(dirname(found.path), reference.path);
+        for (const candidate of [target, resolve(target, "tsconfig.json")]) {
+            try {
+                await readFile(candidate, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const referenced = { path: candidate, config: parseTsconfig(candidate) };
+            if (compiles(library, referenced, file)) {
+                return referenced.config.compilerOptions ?? {};
+            }
+            break;
+        }
+    }
+    return found.config.compilerOptions ?? {};
+};
+/**
+ * The import extension for the generated client at `file` (absolute), in the project
+ * at `cwd`, from the tsconfig `named` (`--tsconfig`, relative to `cwd`) or found.
+ * Throws a `TsconfigRefusal` when there is none to follow.
+ */
+export const importExtensionOf = async (cwd, file, named) => {
+    const options = await compilerOptionsOf(cwd, file, named);
+    if (options.allowImportingTsExtensions === true ||
+        options.rewriteRelativeImportExtensions === true) {
+        return ".ts";
+    }
+    const lower = (value) => typeof value === "string" ? value.toLowerCase() : "";
+    return lower(options.module) === "commonjs" ||
+        lower(options.moduleResolution) === "bundler"
+        ? ""
+        : ".js";
+};

package/dist/generator/typescript-literal.writer.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `value` as a TypeScript literal starting at column `indent` tabs deep (a tab counts
+ * as two columns), every opened line indented one tab more.
+ */
+export declare const typescriptLiteral: (value: unknown, indent?: number) => string;

package/dist/generator/typescript-literal.writer.js

@@ -0,0 +1,42 @@
+// JSON data written as a TypeScript literal for a generated file: an object or a list
+// stays on one line when that line fits, and opens one member a line when it does
+// not; a key is bare when it is an identifier. Members are written in the order they
+// are given, so the caller decides the order (the generated files give a sorted or
+// canonical one), and the same value always gives the same text.
+/** The column a one-line value may reach, its indentation included. */
+const WIDTH = 100;
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const keyOf = (key) => IDENTIFIER.test(key) ? key : JSON.stringify(key);
+const oneLine = (value) => {
+    if (Array.isArray(value)) {
+        return `[${value.map(oneLine).join(", ")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const members = Object.entries(value).filter(([, member]) => member !== undefined);
+        return members.length === 0
+            ? "{}"
+            : `{ ${members.map(([key, member]) => `${keyOf(key)}: ${oneLine(member)}`).join(", ")} }`;
+    }
+    return JSON.stringify(value);
+};
+/**
+ * `value` as a TypeScript literal starting at column `indent` tabs deep (a tab counts
+ * as two columns), every opened line indented one tab more.
+ */
+export const typescriptLiteral = (value, indent = 0) => {
+    const flat = oneLine(value);
+    if (typeof value !== "object" ||
+        value === null ||
+        indent * 2 + flat.length <= WIDTH) {
+        return flat;
+    }
+    const inner = "\t".repeat(indent + 1);
+    const close = "\t".repeat(indent);
+    if (Array.isArray(value)) {
+        return value.length === 0
+            ? "[]"
+            : `[\n${value.map((item) => `${inner}${typescriptLiteral(item, indent + 1)},`).join("\n")}\n${close}]`;
+    }
+    const members = Object.entries(value).filter(([, member]) => member !== undefined);
+    return `{\n${members.map(([key, member]) => `${inner}${keyOf(key)}: ${typescriptLiteral(member, indent + 1)},`).join("\n")}\n${close}}`;
+};

package/dist/guardrails/guardrails-contract.d.ts

@@ -0,0 +1,45 @@
+import type { AccessAction, AccessClaimType, AccessPrincipalCondition } from "../policies-contract.js";
+/** The format marker of every guardrails file (`AccessGuardrails["format"]`). */
+export declare const GUARDRAILS_FORMAT: AccessGuardrails["format"];
+/**
+ * The Resources a guardrail narrows: `"*"`, every Resource of every namespace, or,
+ * per namespace, `"*"` (all of that namespace's Resources) or a list of them. A
+ * service applies only its own namespace's list and leaves the others' alone.
+ */
+export type AccessGuardrailResources = "*" | {
+    readonly [namespace: string]: "*" | readonly [string, ...string[]];
+};
+/** One guardrail: a deny on whole Resources, when the principal condition holds (always, without one). */
+export type AccessGuardrailRule = {
+    readonly id: string;
+    readonly actions: "*" | readonly AccessAction[];
+    readonly resources: AccessGuardrailResources;
+    readonly if?: AccessPrincipalCondition;
+};
+/** The `guardrails@1` file: the claims its guardrails compare, by type, and the guardrails. */
+export type AccessGuardrails = {
+    readonly format: "aventara-access/guardrails@1";
+    readonly claims: {
+        readonly [claim: string]: AccessClaimType;
+    };
+    readonly denies: readonly AccessGuardrailRule[];
+};
+/**
+ * A guardrails file as a JSON import types it: `resolveJsonModule` widens `format` to
+ * `string` and each tuple to an array, so the file `avaccess pull` wrote, imported
+ * with `import guardrails from "./access/guardrails.json" with { type: "json" }`, is
+ * not an `AccessGuardrails`. `policies.guardrails` and the engine take it as it is:
+ * only its outline is typed, and the engine checks the rest when it is built. A
+ * policies file (it has `schema` and `grants`) is not one.
+ */
+export type AccessGuardrailsJson = {
+    readonly format: string;
+    readonly claims: {
+        readonly [claim: string]: {
+            readonly scalar: string;
+        };
+    };
+    readonly denies: readonly object[];
+    readonly schema?: never;
+    readonly grants?: never;
+};

package/dist/guardrails/guardrails-contract.js

@@ -0,0 +1,12 @@
+// The org's guardrails file, format `aventara-access/guardrails@1`. Central Access
+// writes it with `defineGuardrails`, the registry serves it to every namespace, and
+// each service's engine applies it on top of the service's own policies file. It is
+// deny-only: the data owner writes the grants, and a guardrail can only narrow what
+// they allow. A guardrail reads the principal alone (its claims and the request's
+// origin) and names whole Resources, by namespace; it never reads a row.
+//
+// Like `policies@1`, it is passive JSON, checked before use, and frozen: a change to
+// its shape is `guardrails@2` beside it. Its canonical byte form and hash are
+// `guardrails.hash.ts`'s.
+/** The format marker of every guardrails file (`AccessGuardrails["format"]`). */
+export const GUARDRAILS_FORMAT = "aventara-access/guardrails@1";

package/dist/guardrails/guardrails.builder.d.ts

@@ -0,0 +1,48 @@
+import type { AccessClaimsDeclaration, AccessClaimsOf } from "../access/claims.mapper.js";
+import type { AccessAction, AccessOrigin } from "../policies-contract.js";
+import type { AccessGuardrailResources, AccessGuardrails } from "./guardrails-contract.js";
+/** The options of a guardrail: its name and the principal condition it applies under. */
+export type AccessGuardrailOptions<C extends AccessClaimsDeclaration> = {
+    /** The guardrail's id (else `guardrail/<actions>#n`). The id is what `explain` and a diff name. */
+    readonly name?: string;
+    /** A condition on the principal alone: its claims, typed from `defineGuardrails({ claims })`, and the request's origin. */
+    readonly if?: {
+        readonly claims?: AccessClaimsOf<C>;
+        readonly origin?: AccessOrigin;
+    };
+};
+declare const guardrailBrand: unique symbol;
+/** A guardrail, as data, before compilation. */
+export type AccessGuardrailDeny = {
+    readonly [guardrailBrand]: true;
+    readonly actions: "*" | AccessAction | readonly [AccessAction, ...AccessAction[]];
+    readonly resources: AccessGuardrailResources;
+    readonly options: {
+        readonly [option: string]: unknown;
+    };
+};
+/** `deny(actions, resources, options?)`: a guardrail. Every guardrail only narrows. */
+export type AccessGuardrailDenyFunction<C extends AccessClaimsDeclaration> = (actions: "*" | AccessAction | readonly [AccessAction, ...AccessAction[]], resources: AccessGuardrailResources, options?: AccessGuardrailOptions<C>) => AccessGuardrailDeny;
+/** The builder `defineGuardrails` returns. It denies and nothing else; each call returns a new builder. */
+export interface AccessGuardrailsBuilder<C extends AccessClaimsDeclaration> {
+    /** Guardrails. Each one denies; none can grant. Order never matters. */
+    denies(rules: (tools: {
+        readonly deny: AccessGuardrailDenyFunction<C>;
+    }) => readonly AccessGuardrailDeny[]): AccessGuardrailsBuilder<C>;
+    /** The compiled `guardrails@1` file. */
+    contract(): AccessGuardrails;
+}
+/** What the builder holds before it compiles. */
+export type AccessGuardrailsDefinition = {
+    readonly claims?: AccessClaimsDeclaration;
+    readonly denies: readonly AccessGuardrailDeny[];
+};
+/**
+ * Starts the org's guardrails: deny-only rules central Access adds on top of every
+ * namespace's own policies. `claims` declares the claims they compare, by type, the
+ * same declaration as `createAccess`'s `policies.claims`.
+ */
+export declare const defineGuardrails: <const C extends AccessClaimsDeclaration = Record<never, never>>(options?: {
+    readonly claims?: C;
+}) => AccessGuardrailsBuilder<C>;
+export {};

package/dist/guardrails/guardrails.builder.js

@@ -0,0 +1,32 @@
+// `defineGuardrails`: the typed authoring API of the org's guardrails. It is
+// deny-only by construction: the builder has `denies` and no `grants`, its callback
+// hands out `deny` and nothing else, and a guardrail's options are a name and a
+// condition on the principal (`if: { claims, origin }`), never a row condition. It
+// compiles to the `guardrails@1` file (`guardrails.compiler.ts`).
+import { compileGuardrails } from "./guardrails.compiler.js";
+const deny = (actions, resources, options = {}) => Object.freeze({
+    actions,
+    resources,
+    options,
+});
+const builderOf = (definition) => ({
+    denies: (rules) => builderOf({
+        ...definition,
+        denies: [
+            ...definition.denies,
+            ...rules({
+                deny: deny,
+            }),
+        ],
+    }),
+    contract: () => compileGuardrails(definition),
+});
+/**
+ * Starts the org's guardrails: deny-only rules central Access adds on top of every
+ * namespace's own policies. `claims` declares the claims they compare, by type, the
+ * same declaration as `createAccess`'s `policies.claims`.
+ */
+export const defineGuardrails = (options) => builderOf({
+    ...(options?.claims !== undefined ? { claims: options.claims } : {}),
+    denies: [],
+});

package/dist/guardrails/guardrails.compiler.d.ts

@@ -0,0 +1,10 @@
+import type { AccessGuardrailsDefinition } from "./guardrails.builder.js";
+import { type AccessGuardrails } from "./guardrails-contract.js";
+/** Compiles the builder's guardrails to the `guardrails@1` file and checks it. */
+export declare const compileGuardrails: (definition: AccessGuardrailsDefinition) => AccessGuardrails;
+/**
+ * Checks a guardrails file before a registry stores it or an engine applies it.
+ * Throws an `Error` naming the guardrail. The file is trusted for nothing it can be
+ * checked for.
+ */
+export declare const checkGuardrails: (guardrails: AccessGuardrails) => void;