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

package/dist/cli/cli.context.js

@@ -0,0 +1,66 @@
+// What every `avaccess` command runs with: the project's directory, the environment,
+// the parsed flags, and where its lines go. A command answers with an exit code, or
+// throws a `CliFailure` that says what to change; the program prints it.
+//
+// Exit codes: 0 the command did what it says (a check passed); 1 it ran and the
+// answer is no (a lock is behind, a file was changed after pull, the registry
+// refused); 2 it could not run (a usage error, missing configuration, an unreadable
+// file, an unreachable registry).
+import { readFile } from "node:fs/promises";
+/** The command did what it says. */
+export const EXIT_OK = 0;
+/** It ran, and the answer is no. */
+export const EXIT_FAILED = 1;
+/** It could not run. */
+export const EXIT_ERROR = 2;
+/** A command's refusal: the exit code, the message, and the error code when Access or the registry named one. */
+export class CliFailure extends Error {
+    exitCode;
+    code;
+    constructor(exitCode, message, code) {
+        super(message);
+        this.exitCode = exitCode;
+        this.code = code;
+    }
+}
+/** A string flag's value, or `undefined`. */
+export const stringFlag = (context, name) => {
+    const value = context.flags[name];
+    return typeof value === "string" && value !== "" ? value : undefined;
+};
+/** The command's positional arguments, refused when there are more or fewer than it takes. */
+export const positionals = (context, usage, min, max) => {
+    if (context.positionals.length < min || context.positionals.length > max) {
+        throw new CliFailure(EXIT_ERROR, `usage: ${usage}`);
+    }
+    return context.positionals;
+};
+/**
+ * A file path inside the project, `/`-separated and relative to it, from a flag's
+ * value; refused when it leaves the project or does not end in `extension`.
+ */
+export const projectFilePath = (value, flag, example, extension) => {
+    const path = value.replace(/\\/g, "/").replace(/^\.\/+/, "");
+    if (path === "" ||
+        path.startsWith("/") ||
+        /^[A-Za-z]:/.test(path) ||
+        path.split("/").includes("..") ||
+        !path.endsWith(extension)) {
+        throw new CliFailure(EXIT_ERROR, `${flag} is a ${extension} file inside the project, such as ${JSON.stringify(example)}; it was ${JSON.stringify(value)}`);
+    }
+    return path;
+};
+/** The version of `@aventara/access` this bin is, from its own manifest. */
+export const versionOf = async () => {
+    const manifest = JSON.parse(await readFile(decodeURIComponent(new URL("../../package.json", import.meta.url).pathname), "utf8"));
+    return manifest.version;
+};
+/** An error's message without the package's prefix: the CLI names itself. */
+export const messageOf = (error) => String(error instanceof Error ? error.message : error).replace(/^Aventara Access: /, "");
+/** The `code` an Access error carries (read by shape: a module the CLI loads may hold its own copy of Access). */
+export const codeOf = (error) => {
+    const code = error?.code;
+    return typeof code === "string" && code.startsWith("ACCESS_")
+        ? code
+        : undefined;
+};

package/dist/cli/diff.command.d.ts

@@ -0,0 +1,2 @@
+import { type CliContext, type ExitCode } from "./cli.context.js";
+export declare const diffCommand: (context: CliContext) => Promise<ExitCode>;

package/dist/cli/diff.command.js

@@ -0,0 +1,66 @@
+// `avaccess diff [<from> [<to>]] [--namespace <namespace>]`: the rules that changed
+// between two revisions of the namespace's policies file, by name. A revision is
+// `lock` (the one `avAccess.lock.json` pins), `head` (the registry's current), its
+// hash, or the start of its hash; `from` defaults to `lock` and `to` to `head`, so a
+// bare `avaccess diff` says what a pull would bring. Both files come from the
+// registry and are hashed again before they are compared.
+import { LOCK_FILE } from "../lock/lock-contract.js";
+import { CliFailure, EXIT_ERROR, EXIT_FAILED, EXIT_OK, positionals, stringFlag, } from "./cli.context.js";
+import { readLockIfAny } from "./lock.file.js";
+import { changeLine, diffPolicies } from "./policies.diff.js";
+import { registryClient } from "./registry.client.js";
+const USAGE = "avaccess diff [<from> [<to>]] [--namespace <namespace>]";
+/** The shortest start of a hash `diff` takes. */
+const MIN_PREFIX = 7;
+/** A revision named on the command line, as the registry's full hash. */
+const resolveRevision = async (reference, namespace, lock, registry) => {
+    if (reference === "lock") {
+        if (lock === undefined || lock.namespace !== namespace) {
+            throw new CliFailure(EXIT_ERROR, `"lock" names the revision ${LOCK_FILE} pins, and the project has no lock for namespace "${namespace}"`);
+        }
+        return lock.policies.hash;
+    }
+    if (reference === "head") {
+        const head = await registry.headHash(namespace);
+        if (head === null) {
+            throw new CliFailure(EXIT_FAILED, `namespace "${namespace}" has no file pushed yet`);
+        }
+        return head;
+    }
+    const hex = reference.replace(/^sha256:/, "").toLowerCase();
+    if (!/^[0-9a-f]+$/.test(hex) || hex.length < MIN_PREFIX || hex.length > 64) {
+        throw new CliFailure(EXIT_ERROR, `a revision is "lock", "head", a hash (sha256:<hex>) or its first ${MIN_PREFIX} or more hex digits; it was ${JSON.stringify(reference)}`);
+    }
+    if (hex.length === 64) {
+        return `sha256:${hex}`;
+    }
+    const matches = (await registry.revisions(namespace)).filter((entry) => entry.hash.startsWith(`sha256:${hex}`));
+    if (matches.length !== 1) {
+        throw new CliFailure(EXIT_FAILED, matches.length === 0
+            ? `namespace "${namespace}" has no revision starting ${reference}`
+            : `${reference} starts ${matches.length} revisions of namespace "${namespace}": give more of the hash`);
+    }
+    return matches[0].hash;
+};
+export const diffCommand = async (context) => {
+    const [from = "lock", to = "head"] = positionals(context, USAGE, 0, 2);
+    const lock = await readLockIfAny(context.cwd);
+    const namespace = stringFlag(context, "namespace") ?? lock?.namespace;
+    if (namespace === undefined) {
+        throw new CliFailure(EXIT_ERROR, `no namespace: pass --namespace <namespace> (the project has no ${LOCK_FILE} to read it from)`);
+    }
+    const registry = registryClient(context);
+    const fromHash = await resolveRevision(from, namespace, lock, registry);
+    const toHash = await resolveRevision(to, namespace, lock, registry);
+    const before = await registry.revision(namespace, fromHash);
+    const after = toHash === fromHash ? before : await registry.revision(namespace, toHash);
+    const changes = diffPolicies(before.file, after.file);
+    context.out(`namespace "${namespace}": ${fromHash} → ${toHash}`);
+    if (changes.length === 0) {
+        context.out("  no rule changed");
+    }
+    for (const change of changes) {
+        context.out(`  ${changeLine(change)}`);
+    }
+    return EXIT_OK;
+};

package/dist/cli/generate.command.d.ts

@@ -0,0 +1,2 @@
+import { type CliContext, type ExitCode } from "./cli.context.js";
+export declare const generateCommand: (context: CliContext) => Promise<ExitCode>;

package/dist/cli/generate.command.js

@@ -0,0 +1,82 @@
+// `avaccess generate --orm <orm> [--out <file>]`: the generated client of a service
+// that does not run on Aventara, written from the pulled files `avAccess.lock.json`
+// pins, with one ORM's translator or none (`--orm none`, the default). Two TypeScript files: `--out` (default
+// `src/generated/avAccess.ts`), which the service imports, and
+// `<name>.internal.ts` beside it, the copied decisions it imports, named with the
+// extension the project's tsconfig asks for (`tsconfig.reader.ts`). It runs the
+// offline check `avaccess verify` runs first: a pulled file edited by hand is refused
+// (`ACCESS_LOCK_MISMATCH`) and nothing is written. No network.
+import { relative, resolve } from "node:path";
+import { emitClient } from "../generator/client.emitter.js";
+import { importExtensionOf, TsconfigRefusal, } from "../generator/tsconfig.reader.js";
+import { composeGuardrails } from "../guardrails/guardrails.composer.js";
+import { canonicalGuardrails } from "../guardrails/guardrails.hash.js";
+import { verifyLocked } from "../lock/lock.verifier.js";
+import { canonicalPolicies } from "../policies.hash.js";
+import { CliFailure, codeOf, EXIT_ERROR, EXIT_FAILED, EXIT_OK, messageOf, positionals, projectFilePath, stringFlag, versionOf, } from "./cli.context.js";
+import { readLock, readPinned, writeProjectFile } from "./lock.file.js";
+import { clientTranslatorOf } from "./translator.flag.js";
+/** Where the generated client goes when `--out` does not say. */
+const DEFAULT_CLIENT = "src/generated/avAccess.ts";
+/** The internal file beside a client file: `avAccess.ts` → `avAccess.internal.ts`. */
+const internalFileOf = (client) => client.replace(/\.ts$/, ".internal.ts");
+export const generateCommand = async (context) => {
+    positionals(context, "avaccess generate [--orm <orm>] [--out <file>] [--tsconfig <file>]", 0, 0);
+    const translator = clientTranslatorOf(context);
+    const out = projectFilePath(stringFlag(context, "out") ?? DEFAULT_CLIENT, "--out", DEFAULT_CLIENT, ".ts");
+    const lock = await readLock(context.cwd);
+    const policies = await readPinned(context.cwd, lock.policies);
+    const guardrails = lock.guardrails === null
+        ? undefined
+        : await readPinned(context.cwd, lock.guardrails);
+    let guardrailDenies = [];
+    try {
+        verifyLocked(lock, {
+            namespace: policies
+                ?.namespace,
+            policies,
+            guardrails,
+        });
+        if (guardrails !== undefined) {
+            // Composed from the canonical forms, so a pulled file's member order (which
+            // its hash ignores) never reaches the client's text.
+            const file = JSON.parse(canonicalPolicies(policies));
+            guardrailDenies = composeGuardrails(file, JSON.parse(canonicalGuardrails(guardrails))).denies.slice(file.denies.length);
+        }
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_FAILED, messageOf(error), codeOf(error));
+    }
+    const internal = internalFileOf(out);
+    // Relative to the project, with forward slashes, as `--out` is: the banner's bytes
+    // do not depend on how the path was typed.
+    const named = stringFlag(context, "tsconfig");
+    const tsconfig = named === undefined
+        ? undefined
+        : relative(context.cwd, resolve(context.cwd, named)).replace(/\\/g, "/");
+    let extension;
+    try {
+        extension = await importExtensionOf(context.cwd, resolve(context.cwd, out), tsconfig);
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, error instanceof TsconfigRefusal
+            ? error.message
+            : `the project's tsconfig.json could not be read to name ${internal} (${messageOf(error)}). Nothing was written.`);
+    }
+    const internalName = (internal.split("/").pop() ?? internal).replace(/\.ts$/, "");
+    const files = await emitClient({
+        policies: policies,
+        guardrailDenies,
+        lock,
+        translator,
+        command: `avaccess generate --orm ${translator.orm} --out ${out}${tsconfig === undefined ? "" : ` --tsconfig ${tsconfig}`}`,
+        version: await versionOf(),
+        internalSpecifier: `./${internalName}${extension}`,
+    });
+    await writeProjectFile(context.cwd, internal, files.internal);
+    await writeProjectFile(context.cwd, out, files.client);
+    context.out(`wrote ${out} and ${internal}: namespace "${lock.namespace}" from ${lock.policies.path}${lock.guardrails === null ? "" : ` and ${lock.guardrails.path}`}, ${translator.title === undefined
+        ? "with no ORM translator (--orm none)"
+        : `with the ${translator.title} translator`}`);
+    return EXIT_OK;
+};

package/dist/cli/keys.command.d.ts

@@ -0,0 +1,2 @@
+import { type CliContext, type ExitCode } from "./cli.context.js";
+export declare const keysCommand: (context: CliContext) => Promise<ExitCode>;

package/dist/cli/keys.command.js

@@ -0,0 +1,96 @@
+// `avaccess keys issue|rotate|revoke`: the operator's side of the registry, run as the
+// operator, never over HTTP. `--server <module>` names the Access server's own module
+// (the one that calls `createAccess({ …, registry: { enabled: true } })` and exports
+// the instance, as its default export or as `access`; or, for a Better Auth app that
+// is the hub, the one that exports `accessOf(auth)` with
+// `aventaraAccess({ registry: { enabled: true } })` in its plugins); the CLI loads it
+// with the server's own configuration and database, and calls `access.registry` in
+// this process. Whoever can run it holds the server's database credentials already, so
+// no key or route of its own opens the operator's API.
+//
+// A key is printed once, by the command that issues it, and never again: the registry
+// keeps only its hash, and no other command prints one.
+//
+//   avaccess keys issue <namespace> --server <module>           a new namespace, its push and pull keys
+//   avaccess keys rotate <namespace> <push|pull> --server <m>   a new key; the previous one is refused
+//   avaccess keys revoke <namespace> <push|pull> --server <m>   the key is refused from now on
+import { isRecord } from "../policies.compiler.js";
+import { CliFailure, codeOf, EXIT_ERROR, EXIT_FAILED, EXIT_OK, messageOf, stringFlag, } from "./cli.context.js";
+import { loadProjectModule, pickExport } from "./module.loader.js";
+const USAGE = [
+    "avaccess keys issue <namespace> --server <module>",
+    "avaccess keys rotate <namespace> <push|pull> --server <module>",
+    "avaccess keys revoke <namespace> <push|pull> --server <module>",
+].join("\n       ");
+/** `createAccess`'s instance (it has the handler), or `accessOf(auth)` (it has the request state). */
+const isAccessInstance = (value) => isRecord(value) &&
+    (typeof value.handler === "function" || typeof value.state === "function");
+/** Better Auth's own instance with the Access plugin in its plugins: its operator API is `accessOf(auth).registry`. */
+const isPluginApp = (instance) => isRecord(instance.options) &&
+    Array.isArray(instance.options.plugins) &&
+    instance.options.plugins.some((plugin) => isRecord(plugin) && plugin.id === "aventara-access") &&
+    typeof instance.api === "object";
+/** The operator's API of the Access server `--server` names. */
+const operatorOf = async (context) => {
+    const server = stringFlag(context, "server");
+    if (server === undefined) {
+        throw new CliFailure(EXIT_ERROR, "no server: pass --server <module>, the Access server's module that exports its `createAccess({ …, registry: { enabled: true } })` instance, or `accessOf(auth)` for a Better Auth app with `aventaraAccess({ registry: { enabled: true } })`");
+    }
+    const exports = await loadProjectModule(context.cwd, server);
+    const instance = pickExport(exports, server, "access", isAccessInstance, "Access instance");
+    const registry = instance.registry;
+    if (!isRecord(registry) || typeof registry.createNamespace !== "function") {
+        if (isPluginApp(instance)) {
+            throw new CliFailure(EXIT_ERROR, `${server} exports Better Auth's own instance: export \`accessOf(auth)\` (from @aventara/access/better-auth) as \`access\`, built with \`aventaraAccess({ registry: { enabled: true } })\`; its \`registry\` is the operator's API`);
+        }
+        throw new CliFailure(EXIT_ERROR, `the Access instance in ${server} has the registry off: build it with \`registry: { enabled: true }\` (on \`createAccess\`, or on \`aventaraAccess()\` for \`accessOf(auth)\`)`);
+    }
+    return registry;
+};
+const kindOf = (kind) => {
+    if (kind !== "push" && kind !== "pull") {
+        throw new CliFailure(EXIT_ERROR, `a key's kind is "push" or "pull"; it was ${JSON.stringify(kind ?? "")}\nusage: ${USAGE}`);
+    }
+    return kind;
+};
+/** Runs one operator call, its refusal as the CLI's. */
+const asOperator = async (run) => {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_FAILED, messageOf(error), codeOf(error));
+    }
+};
+export const keysCommand = async (context) => {
+    const [action, namespace, kind, ...rest] = context.positionals;
+    const arity = action === "issue" ? 2 : 3;
+    if ((action !== "issue" && action !== "rotate" && action !== "revoke") ||
+        namespace === undefined ||
+        context.positionals.length !== arity ||
+        rest.length > 0) {
+        throw new CliFailure(EXIT_ERROR, `usage: ${USAGE}`);
+    }
+    if (action !== "issue") {
+        kindOf(kind);
+    }
+    const operator = await operatorOf(context);
+    if (action === "issue") {
+        const keys = await asOperator(() => operator.createNamespace(namespace));
+        context.out(`namespace "${keys.namespace}" created. Its keys, shown this once (the registry keeps only their hashes):`);
+        context.out(`  push key: ${keys.push}`);
+        context.out(`  pull key: ${keys.pull}`);
+        context.out("Give each to the service as AVACCESS_KEY, kept as a secret: the push key where it pushes (its CI), the pull key where it only pulls.");
+        return EXIT_OK;
+    }
+    const checked = kindOf(kind);
+    if (action === "rotate") {
+        const key = await asOperator(() => operator.rotateKey(namespace, checked));
+        context.out(`the ${checked} key of namespace "${namespace}", shown this once: ${key}`);
+        context.out(`The previous ${checked} key is refused from now on: give this one to the service as AVACCESS_KEY.`);
+        return EXIT_OK;
+    }
+    await asOperator(() => operator.revokeKey(namespace, checked));
+    context.out(`the ${checked} key of namespace "${namespace}" is revoked: it is refused from now on. \`avaccess keys rotate ${namespace} ${checked}\` issues a new one.`);
+    return EXIT_OK;
+};

package/dist/cli/lock.file.d.ts

@@ -0,0 +1,31 @@
+import { type AccessForeignFacts } from "../foreign/foreign-facts.js";
+import { type AccessLock, type AccessLockPin } from "../lock/lock-contract.js";
+/** The project's lock, checked; a missing or malformed one is refused, naming the fix. */
+export declare const readLock: (cwd: string) => Promise<AccessLock>;
+/** The project's lock, or `undefined` when it has none yet. */
+export declare const readLockIfAny: (cwd: string) => Promise<AccessLock | undefined>;
+/** A pinned file, parsed. A missing or unparsable one fails the check (`ACCESS_LOCK_MISMATCH`). */
+export declare const readPinned: (cwd: string, pin: AccessLockPin) => Promise<unknown>;
+/**
+ * The foreign facts the lock pins, held to their pin and to the lock's namespace;
+ * `undefined` when it pins none. A changed file fails the check
+ * (`ACCESS_LOCK_MISMATCH`).
+ */
+export declare const readForeignPinned: (cwd: string, lock: AccessLock) => Promise<AccessForeignFacts | undefined>;
+/** JSON text as the CLI writes it: two-space indent, a final newline. */
+export declare const jsonText: (value: unknown) => string;
+/**
+ * Writes a file under the project in one step: a temporary file beside it, created
+ * new (never one that is there already, nor a link), then a rename over the file.
+ * A path whose directory leaves the project through a symbolic link is refused.
+ *
+ * The temporary file is created in the directory's canonical path, read once its
+ * symbolic links are resolved and held inside the project, so a link on the way
+ * that is swapped after the check cannot move it out. It is written only once that
+ * path still names the file just created (a directory on the way replaced by a link
+ * since is refused, the file removed), and renamed within that same directory. A
+ * window stays where a real directory on the way is renamed away and replaced by a
+ * link between that last check and the rename: Node.js opens no file relative to a
+ * directory it holds open, so no path-based write closes it entirely.
+ */
+export declare const writeProjectFile: (cwd: string, path: string, text: string) => Promise<void>;

package/dist/cli/lock.file.js

@@ -0,0 +1,181 @@
+// `avAccess.lock.json` and the pulled files on disk. `avaccess pull` writes them,
+// `verify`, `status` and `diff` read them. A pulled file is written in its canonical
+// member order, indented for review; its hash is over the parsed file, so a
+// formatter that re-indents it changes nothing, and an edit of a name or a literal
+// changes the hash.
+import { mkdir, open, readFile, realpath, rename, stat, unlink, } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { checkForeignFacts, foreignFactsHash, } from "../foreign/foreign-facts.js";
+import { checkLock, LOCK_FILE, } from "../lock/lock-contract.js";
+import { CliFailure, EXIT_ERROR, EXIT_FAILED, messageOf, } from "./cli.context.js";
+const isMissing = (error) => error?.code === "ENOENT";
+/** The project's lock, checked; a missing or malformed one is refused, naming the fix. */
+export const readLock = async (cwd) => {
+    let text;
+    try {
+        text = await readFile(resolve(cwd, LOCK_FILE), "utf8");
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, isMissing(error)
+            ? `no ${LOCK_FILE} in ${cwd}: run \`avaccess pull --namespace <namespace>\` first`
+            : `${LOCK_FILE} could not be read (${messageOf(error)})`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, `${LOCK_FILE} is not JSON (${messageOf(error)}): pull again with \`avaccess pull\``);
+    }
+    try {
+        return checkLock(parsed, LOCK_FILE);
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, messageOf(error));
+    }
+};
+/** The project's lock, or `undefined` when it has none yet. */
+export const readLockIfAny = async (cwd) => {
+    try {
+        await readFile(resolve(cwd, LOCK_FILE), "utf8");
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return undefined;
+        }
+    }
+    return readLock(cwd);
+};
+/** A pinned file, parsed. A missing or unparsable one fails the check (`ACCESS_LOCK_MISMATCH`). */
+export const readPinned = async (cwd, pin) => {
+    let text;
+    try {
+        text = await readFile(resolve(cwd, pin.path), "utf8");
+    }
+    catch (error) {
+        throw new CliFailure(isMissing(error) ? EXIT_FAILED : EXIT_ERROR, isMissing(error)
+            ? `${pin.path} is pinned in ${LOCK_FILE} under ${pin.hash}, and is missing: pull it again with \`avaccess pull\``
+            : `${pin.path} could not be read (${messageOf(error)})`, isMissing(error) ? "ACCESS_LOCK_MISMATCH" : undefined);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_FAILED, `${pin.path} is pinned in ${LOCK_FILE} under ${pin.hash}, and is no longer JSON (${messageOf(error)}): it was changed after it was pulled. Pull it again with \`avaccess pull\`; a pulled file is never edited by hand`, "ACCESS_LOCK_MISMATCH");
+    }
+};
+/**
+ * The foreign facts the lock pins, held to their pin and to the lock's namespace;
+ * `undefined` when it pins none. A changed file fails the check
+ * (`ACCESS_LOCK_MISMATCH`).
+ */
+export const readForeignPinned = async (cwd, lock) => {
+    const pin = lock.foreign;
+    if (pin === undefined) {
+        return undefined;
+    }
+    let facts;
+    let hash;
+    try {
+        facts = checkForeignFacts(await readPinned(cwd, pin));
+        hash = foreignFactsHash(facts);
+    }
+    catch (error) {
+        if (error instanceof CliFailure) {
+            throw error;
+        }
+        throw new CliFailure(EXIT_FAILED, `${pin.path} is pinned in ${LOCK_FILE} under ${pin.hash}, and is no longer a foreign facts file (${messageOf(error)}): it was changed after it was pulled. Pull it again with \`avaccess pull\`; a pulled file is never edited by hand`, "ACCESS_LOCK_MISMATCH");
+    }
+    if (hash !== pin.hash) {
+        throw new CliFailure(EXIT_FAILED, `${pin.path} hashes to ${hash}, and ${LOCK_FILE} pins ${pin.hash}: it was changed after it was pulled. Pull it again with \`avaccess pull\`; a pulled file is never edited by hand`, "ACCESS_LOCK_MISMATCH");
+    }
+    if (facts.namespace !== lock.namespace) {
+        throw new CliFailure(EXIT_FAILED, `${pin.path} holds what namespace "${facts.namespace}" reads, and ${LOCK_FILE} pins namespace "${lock.namespace}": pull this project's own namespace again with \`avaccess pull\``, "ACCESS_LOCK_MISMATCH");
+    }
+    return facts;
+};
+/** JSON text as the CLI writes it: two-space indent, a final newline. */
+export const jsonText = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** Whether `real`, a canonical path, is `root` or under it. */
+const within = (root, real) => real === root || real.startsWith(`${root}${sep}`);
+/** The refusal of a path that leaves the project through a symbolic link. */
+const leaves = (path, real) => new CliFailure(EXIT_ERROR, `${path} leaves the project through a symbolic link (its directory resolves to ${real}); avaccess writes only inside the project. Nothing was written there`);
+/**
+ * Refuses `path` when its directory, as far as it exists, resolves outside the
+ * project: a directory on the way that is a symbolic link out of it.
+ */
+const holdInside = async (cwd, path) => {
+    const root = await realpath(cwd);
+    let directory = dirname(resolve(cwd, path));
+    for (;;) {
+        let real;
+        try {
+            real = await realpath(directory);
+        }
+        catch (error) {
+            const parent = dirname(directory);
+            if (isMissing(error) && parent !== directory) {
+                directory = parent;
+                continue;
+            }
+            throw error;
+        }
+        if (!within(root, real)) {
+            throw leaves(path, real);
+        }
+        return;
+    }
+};
+/**
+ * Writes a file under the project in one step: a temporary file beside it, created
+ * new (never one that is there already, nor a link), then a rename over the file.
+ * A path whose directory leaves the project through a symbolic link is refused.
+ *
+ * The temporary file is created in the directory's canonical path, read once its
+ * symbolic links are resolved and held inside the project, so a link on the way
+ * that is swapped after the check cannot move it out. It is written only once that
+ * path still names the file just created (a directory on the way replaced by a link
+ * since is refused, the file removed), and renamed within that same directory. A
+ * window stays where a real directory on the way is renamed away and replaced by a
+ * link between that last check and the rename: Node.js opens no file relative to a
+ * directory it holds open, so no path-based write closes it entirely.
+ */
+export const writeProjectFile = async (cwd, path, text) => {
+    const target = resolve(cwd, path);
+    await holdInside(cwd, path);
+    await mkdir(dirname(target), { recursive: true });
+    const root = await realpath(cwd);
+    const directory = await realpath(dirname(target));
+    if (!within(root, directory)) {
+        throw leaves(path, directory);
+    }
+    const temporary = join(directory, `${basename(target)}.${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}.tmp`);
+    const handle = await open(temporary, "wx");
+    let kept = false;
+    try {
+        const created = await handle.stat();
+        let named;
+        let real;
+        try {
+            named = await stat(temporary);
+            real = await realpath(temporary);
+        }
+        catch {
+            throw leaves(path, directory);
+        }
+        if (real !== temporary ||
+            created.dev !== named.dev ||
+            created.ino !== named.ino) {
+            throw leaves(path, dirname(real));
+        }
+        await handle.writeFile(text);
+        kept = true;
+    }
+    finally {
+        await handle.close();
+        if (!kept) {
+            await unlink(temporary).catch(() => undefined);
+        }
+    }
+    await rename(temporary, join(directory, basename(target)));
+};

package/dist/cli/module.loader.d.ts

@@ -0,0 +1,13 @@
+/** A module's exports, by name (`default` included). */
+type ModuleExports = {
+    readonly [name: string]: unknown;
+};
+/** The exports of the project's module at `path` (a `.json` file is `{ default: <its value> }`). */
+export declare const loadProjectModule: (cwd: string, path: string) => Promise<ModuleExports>;
+/**
+ * The one export of `exports` that `accepts`: `default`, else the export named
+ * `preferred`, else the only export that fits. Names what it found when that is
+ * not one.
+ */
+export declare const pickExport: <T>(exports: ModuleExports, path: string, preferred: string, accepts: (value: unknown) => value is T, what: string) => T;
+export {};

package/dist/cli/module.loader.js

@@ -0,0 +1,63 @@
+// The project's own modules, as `avaccess` reads them: a `.json` file is parsed; a
+// TypeScript or JavaScript module (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`) is
+// loaded with jiti, the loader `prisma.config.ts` and the framework's configs are
+// read with, so a project's sources load as they are, with no build step. jiti keeps
+// no cache on disk here: the CLI writes nothing but what a command says it writes.
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { CliFailure, EXIT_ERROR, messageOf } from "./cli.context.js";
+const MODULE = /\.(?:[cm]?ts|[cm]?js)$/;
+/** The exports of the project's module at `path` (a `.json` file is `{ default: <its value> }`). */
+export const loadProjectModule = async (cwd, path) => {
+    const file = resolve(cwd, path);
+    if (file.endsWith(".json")) {
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch (error) {
+            throw new CliFailure(EXIT_ERROR, `${path} could not be read (${messageOf(error)})`);
+        }
+        try {
+            return { default: JSON.parse(text) };
+        }
+        catch (error) {
+            throw new CliFailure(EXIT_ERROR, `${path} is not JSON (${messageOf(error)})`);
+        }
+    }
+    if (!MODULE.test(file)) {
+        throw new CliFailure(EXIT_ERROR, `${path} is neither a .json file nor a module (.ts, .mts, .cts, .js, .mjs, .cjs)`);
+    }
+    const { createJiti } = await import("jiti");
+    const jiti = createJiti(import.meta.url, {
+        fsCache: false,
+        moduleCache: false,
+        interopDefault: false,
+    });
+    try {
+        return (await jiti.import(file));
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, `${path} could not be loaded: ${messageOf(error)}`);
+    }
+};
+/**
+ * The one export of `exports` that `accepts`: `default`, else the export named
+ * `preferred`, else the only export that fits. Names what it found when that is
+ * not one.
+ */
+export const pickExport = (exports, path, preferred, accepts, what) => {
+    for (const name of ["default", preferred]) {
+        const value = exports[name];
+        if (accepts(value)) {
+            return value;
+        }
+    }
+    const fitting = Object.entries(exports).filter(([, value]) => accepts(value));
+    if (fitting.length === 1) {
+        return fitting[0][1];
+    }
+    throw new CliFailure(EXIT_ERROR, fitting.length === 0
+        ? `${path} exports no ${what}: export it as the default export or as \`${preferred}\``
+        : `${path} exports ${fitting.length} ${what}s (${fitting.map(([name]) => name).join(", ")}): export the one to use as the default export or as \`${preferred}\``);
+};

package/dist/cli/policies.diff.d.ts

@@ -0,0 +1,16 @@
+import type { AccessPolicies } from "../policies-contract.js";
+/** One part of a policies file a change names. */
+type PoliciesPart = "namespace" | "claim" | "schema" | "role" | "govern" | "grant" | "deny";
+/** One named change between two revisions. */
+type PoliciesChange = {
+    readonly part: PoliciesPart;
+    readonly name: string;
+    readonly change: "added" | "removed" | "changed";
+    /** For a changed entry: its members that differ. */
+    readonly members?: readonly string[];
+};
+/** The named changes from `before` to `after`, in the order of the file's parts. */
+export declare const diffPolicies: (before: AccessPolicies, after: AccessPolicies) => readonly PoliciesChange[];
+/** A change as one line: `grant "Note/read/player#1": changed (where)`. */
+export declare const changeLine: (change: PoliciesChange) => string;
+export {};