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

package/dist/cli/avaccess.program.js

@@ -0,0 +1,166 @@
+// The `avaccess` program: the command line read, the command run, its refusal printed
+// and its exit code returned. The bin (`avaccess.bin.ts`) only calls it.
+import { parseArgs } from "node:util";
+import { CLIENT_TRANSLATORS, ORM_TRANSLATORS, } from "../generator/orm.translator.js";
+import { ENV_VARIABLE } from "./beacon-pins.file.js";
+import { CliFailure, EXIT_ERROR, EXIT_OK, messageOf, versionOf, } from "./cli.context.js";
+import { diffCommand } from "./diff.command.js";
+import { generateCommand } from "./generate.command.js";
+import { keysCommand } from "./keys.command.js";
+import { pullCommand } from "./pull.command.js";
+import { pushCommand } from "./push.command.js";
+import { KEY_VARIABLE, REGISTRY_URL_VARIABLE } from "./registry.client.js";
+import { schemaCommand } from "./schema.command.js";
+import { MIGRATE_VARIABLE, PORT_VARIABLE, serveCommand, } from "./serve.command.js";
+import { statusCommand } from "./status.command.js";
+import { verifyCommand } from "./verify.command.js";
+const REGISTRY = { type: "string" };
+const NAMESPACE = { type: "string" };
+const ORM = { type: "string" };
+const BEACON = { type: "string" };
+const ENV = { type: "string" };
+/** Each command, what it runs, the flags it takes and its line in the help. */
+const COMMANDS = {
+    push: {
+        run: pushCommand,
+        flags: { registry: REGISTRY, beacon: BEACON },
+        help: "push <rules> [--beacon <module>]   push the namespace's policies file (a .json file, or the module holding the rules); --beacon sends the namespace's beacon and those of the namespaces it reads as foreign",
+    },
+    pull: {
+        run: pullCommand,
+        flags: {
+            registry: REGISTRY,
+            namespace: NAMESPACE,
+            out: { type: "string" },
+            foreign: { type: "string", multiple: true },
+            beacon: BEACON,
+            env: ENV,
+        },
+        help: "pull [--namespace <ns>] [--out <dir>] [--foreign <ns>:<Resource>,…] [--beacon <module>] [--env <env>]   pull the namespace's file and the org's guardrails, and the foreign facts --foreign names; pin them in avAccess.lock.json, and the beacons of the namespaces read as foreign (checked through --beacon) in avAccess.beacons.<env>.json",
+    },
+    status: {
+        run: statusCommand,
+        flags: { registry: REGISTRY },
+        help: "status                       is avAccess.lock.json behind the registry? (exit 1 when it is)",
+    },
+    diff: {
+        run: diffCommand,
+        flags: { registry: REGISTRY, namespace: NAMESPACE },
+        help: "diff [<from> [<to>]] [--namespace <ns>]   the rules that changed between two revisions (lock, head, a hash); default lock → head",
+    },
+    verify: {
+        run: verifyCommand,
+        flags: { env: ENV },
+        help: "verify [--env <env>]         the pulled files against avAccess.lock.json, and each avAccess.beacons.<env>.json against the rules, offline (exit 1 on a changed file)",
+    },
+    generate: {
+        run: generateCommand,
+        flags: { orm: ORM, out: { type: "string" }, tsconfig: { type: "string" } },
+        help: "generate [--orm <orm>] [--out <file>] [--tsconfig <file>]   the client of a service not on Aventara, from the pulled files: --out and <name>.internal.ts beside it (default orm: none; default out: src/generated/avAccess.ts)",
+    },
+    schema: {
+        run: schemaCommand,
+        flags: { orm: ORM, schema: { type: "string" }, out: { type: "string" } },
+        help: "schema --orm <orm> [--schema <path>] [--out <file>]   the AccessSchema of the ORM's schema, to author rules with definePolicies (default out: src/generated/avAccess.schema.ts)",
+    },
+    serve: {
+        run: serveCommand,
+        flags: {
+            config: { type: "string" },
+            port: { type: "string" },
+            hostname: { type: "string" },
+            "max-body-bytes": { type: "string" },
+            migrate: { type: "boolean" },
+        },
+        help: "serve [--config <file>] [--port <port>] [--hostname <host>] [--max-body-bytes <bytes>] [--migrate]   the standalone host, serving access.config.ts's instance on 127.0.0.1 unless --hostname says (--migrate or AVACCESS_MIGRATE=true runs Better Auth's migration first)",
+    },
+    keys: {
+        run: keysCommand,
+        flags: { server: { type: "string" } },
+        help: "keys issue <ns> | rotate <ns> <push|pull> | revoke <ns> <push|pull> --server <module>   the operator's keys",
+    },
+};
+const isCommand = (name) => Object.hasOwn(COMMANDS, name);
+const HELP = [
+    "avaccess: the Aventara Access registry, from a project",
+    "",
+    "usage: avaccess <command> [arguments] [flags]",
+    "",
+    ...Object.values(COMMANDS).map((command) => `  ${command.help}`),
+    "",
+    `The registry: --registry <url> or ${REGISTRY_URL_VARIABLE} (the Access server's URL).`,
+    `The key: ${KEY_VARIABLE}, the namespace's push or pull key (never a flag).`,
+    `The environment (beacon pins): --env <env> or ${ENV_VARIABLE}.`,
+    `serve: the port from --port or ${PORT_VARIABLE} (default 3000); the migration on start only with --migrate or ${MIGRATE_VARIABLE}=true.`,
+    `The translators (--orm): for generate ${Object.keys(CLIENT_TRANSLATORS).sort().join(", ")} (default none); for schema, required, ${Object.keys(ORM_TRANSLATORS).sort().join(", ")}.`,
+    "Exit codes: 0 done; 1 the check failed or the registry refused; 2 the command could not run.",
+].join("\n");
+/** The control characters but the line feed (U+0000 to U+001F, U+007F to U+009F): what a terminal may act on. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the characters it removes
+const TERMINAL_CONTROL = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/g;
+/** A line as the program prints it: whatever text it carries, no terminal control. */
+const plain = (line) => line.replace(TERMINAL_CONTROL, " ");
+/** Never resolves: a program run without a way to be stopped serves until its process ends. */
+const NEVER_STOPPED = () => new Promise(() => { });
+/**
+ * Runs `avaccess` with `args` (the command line after the bin's name) in `cwd`, and
+ * answers its exit code. `untilStopped` resolves when a command that runs until
+ * stopped (`serve`) should stop; the bin resolves it on SIGTERM or SIGINT.
+ */
+export const runAvaccess = async (args, cwd, env, printed, untilStopped = NEVER_STOPPED) => {
+    const output = {
+        out: (line) => printed.out(plain(line)),
+        err: (line) => printed.err(plain(line)),
+    };
+    const [name, ...rest] = args;
+    if (name === undefined ||
+        name === "help" ||
+        name === "--help" ||
+        name === "-h") {
+        output.out(HELP);
+        return name === undefined ? EXIT_ERROR : EXIT_OK;
+    }
+    if (name === "--version" || name === "-v") {
+        output.out(await versionOf());
+        return EXIT_OK;
+    }
+    if (!isCommand(name)) {
+        output.err(`avaccess: no command ${JSON.stringify(name)}\n\n${HELP}`);
+        return EXIT_ERROR;
+    }
+    const command = COMMANDS[name];
+    try {
+        let parsed;
+        try {
+            parsed = parseArgs({
+                args: rest,
+                options: { ...command.flags, help: { type: "boolean", short: "h" } },
+                allowPositionals: true,
+                strict: true,
+            });
+        }
+        catch (error) {
+            throw new CliFailure(EXIT_ERROR, `${messageOf(error)}\nusage: avaccess ${command.help}`);
+        }
+        if (parsed.values.help === true) {
+            output.out(`usage: avaccess ${command.help}`);
+            return EXIT_OK;
+        }
+        return await command.run({
+            cwd,
+            env,
+            flags: parsed.values,
+            positionals: parsed.positionals,
+            out: output.out,
+            untilStopped,
+        });
+    }
+    catch (error) {
+        if (error instanceof CliFailure) {
+            output.err(`avaccess ${name}: ${error.code === undefined ? "" : `${error.code}: `}${error.message}`);
+            return error.exitCode;
+        }
+        output.err(`avaccess ${name}: ${messageOf(error)}`);
+        return EXIT_ERROR;
+    }
+};

package/dist/cli/beacon-pins.file.d.ts

@@ -0,0 +1,14 @@
+import { type CliContext } from "./cli.context.js";
+/** The environment variable that names the environment, when `--env` does not. */
+export declare const ENV_VARIABLE = "AVACCESS_ENV";
+/** The pins file of `environment`, at the project's root. */
+export declare const beaconPinsFile: (environment: string) => string;
+/** The environment `--env` or `AVACCESS_ENV` selects; `undefined` when neither does. */
+export declare const environmentOf: (context: CliContext) => string | undefined;
+/**
+ * Checks every `avAccess.beacons.<environment>.json` in the project against the
+ * lock's namespace and the `owners` its pulled file reads, and that `selected`'s is
+ * there when one is selected. Answers the environments checked. A file that fails
+ * the check fails it (`ACCESS_LOCK_MISMATCH`).
+ */
+export declare const verifyBeaconPins: (cwd: string, namespace: string, owners: readonly string[], selected: string | undefined) => Promise<readonly string[]>;

package/dist/cli/beacon-pins.file.js

@@ -0,0 +1,62 @@
+// `avAccess.beacons.<environment>.json`: one environment's beacon pins. A beacon is
+// its database's own, so a staging and a production database have different ones;
+// the pins live beside `avAccess.lock.json` in one file per environment, and the lock
+// itself (the policy and foreign facts hashes) holds against any registry.
+//
+// The environment is `--env <name>`, else `AVACCESS_ENV`, as the registry's URL is
+// `--registry` else `AVACCESS_REGISTRY_URL`. `avaccess pull` writes the selected
+// environment's file; `avaccess verify` checks every one in the project, and the
+// selected one must be there. At startup the app hands its environment's pins to
+// `checkBeacons`, read from this file or from its own environment.
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { beaconPinsProblem, } from "../beacon/beacon.check.js";
+import { CliFailure, EXIT_ERROR, EXIT_FAILED, messageOf, stringFlag, } from "./cli.context.js";
+/** The environment variable that names the environment, when `--env` does not. */
+export const ENV_VARIABLE = "AVACCESS_ENV";
+const ENVIRONMENT = /^[a-z][a-z0-9_-]{0,62}$/;
+const FILE = /^avAccess\.beacons\.([a-z][a-z0-9_-]{0,62})\.json$/;
+/** The pins file of `environment`, at the project's root. */
+export const beaconPinsFile = (environment) => `avAccess.beacons.${environment}.json`;
+/** The environment `--env` or `AVACCESS_ENV` selects; `undefined` when neither does. */
+export const environmentOf = (context) => {
+    const given = stringFlag(context, "env") ?? context.env[ENV_VARIABLE];
+    if (given === undefined || given === "") {
+        return undefined;
+    }
+    if (!ENVIRONMENT.test(given)) {
+        throw new CliFailure(EXIT_ERROR, `the environment ${JSON.stringify(given)} is not an environment name (a lowercase letter, then lowercase letters, digits, "_" or "-"; such as "production")`);
+    }
+    return given;
+};
+/**
+ * Checks every `avAccess.beacons.<environment>.json` in the project against the
+ * lock's namespace and the `owners` its pulled file reads, and that `selected`'s is
+ * there when one is selected. Answers the environments checked. A file that fails
+ * the check fails it (`ACCESS_LOCK_MISMATCH`).
+ */
+export const verifyBeaconPins = async (cwd, namespace, owners, selected) => {
+    const environments = (await readdir(cwd, { withFileTypes: true }))
+        .filter((entry) => entry.isFile())
+        .map((entry) => FILE.exec(entry.name)?.[1])
+        .filter((name) => name !== undefined)
+        .sort();
+    if (selected !== undefined && !environments.includes(selected)) {
+        throw new CliFailure(EXIT_FAILED, `no ${beaconPinsFile(selected)}: the rules ${owners.length === 0 ? "need no beacon pins" : `read ${owners.map((owner) => `"${owner}"`).join(", ")} as foreign`}, and environment "${selected}" has no pins. Pull them with \`avaccess pull --env ${selected} --beacon <module>\``, "ACCESS_LOCK_MISMATCH");
+    }
+    for (const environment of environments) {
+        const path = beaconPinsFile(environment);
+        let pins;
+        try {
+            pins = JSON.parse(await readFile(resolve(cwd, path), "utf8"));
+        }
+        catch (error) {
+            throw new CliFailure(EXIT_FAILED, `${path} is no longer JSON (${messageOf(error)}): pull it again with \`avaccess pull --env ${environment} --beacon <module>\``, "ACCESS_LOCK_MISMATCH");
+        }
+        const problem = beaconPinsProblem(namespace, owners, pins, environment);
+        if (problem !== undefined) {
+            throw new CliFailure(EXIT_FAILED, `${path}: ${problem}`, "ACCESS_LOCK_MISMATCH");
+        }
+    }
+    return environments;
+};

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

@@ -0,0 +1,20 @@
+import { type AccessBeaconStore } from "../beacon/beacon.store.js";
+import { type CliContext } from "./cli.context.js";
+/** The store `--beacon` names; `undefined` when the flag is not given. */
+export declare const beaconStoreOf: (context: CliContext) => Promise<AccessBeaconStore | undefined>;
+/**
+ * The namespace's own beacon, its row written the first time; a row the registry
+ * does not hold (`registered`) is refused, never adopted (`ensureBeacon`).
+ */
+export declare const ownBeacon: (store: AccessBeaconStore, namespace: string, registered: string | null) => Promise<string>;
+/**
+ * `owner`'s beacon as the store's connection reads it. No row, or a row that holds
+ * no beacon, is refused here: the service does not reach `owner`'s database, and the
+ * registry would refuse the push for it.
+ */
+export declare const readOwnerBeacon: (store: AccessBeaconStore, owner: string) => Promise<string>;
+/**
+ * Holds `owner`'s beacon, as the store reads it, to the hash `owner` pushed (`null`:
+ * none): the pull's check that this service reaches `owner`'s database.
+ */
+export declare const holdOwnerBeacon: (store: AccessBeaconStore, owner: string, pushed: string | null) => Promise<void>;

package/dist/cli/beacon.loader.js

@@ -0,0 +1,71 @@
+// `--beacon <module>`: the project's beacon store, for `avaccess push` and `avaccess
+// pull`. The module (TypeScript or JavaScript, loaded as `push <rules>` loads the
+// rules) exports an `AccessBeaconStore` over the service's own data layer, as its
+// default export or as `beacon`: `read(namespace)` reads a namespace's row in
+// `_aventara_beacon`, `create(namespace, value)` writes one. The CLI uses it to write
+// and read the namespace's own beacon, and to read the beacons of the namespaces its
+// rules read as foreign, through the connection the service itself runs on. No line
+// it prints quotes a beacon.
+import { beaconHashOf } from "../beacon/beacon.check.js";
+import { BEACON_TABLE, ensureBeacon, isBeacon, } from "../beacon/beacon.store.js";
+import { isRecord } from "../policies.compiler.js";
+import { CliFailure, codeOf, EXIT_ERROR, EXIT_FAILED, messageOf, stringFlag, } from "./cli.context.js";
+import { loadProjectModule, pickExport } from "./module.loader.js";
+const isStore = (value) => isRecord(value) &&
+    typeof value.read === "function" &&
+    typeof value.create === "function";
+/** The store `--beacon` names; `undefined` when the flag is not given. */
+export const beaconStoreOf = async (context) => {
+    const path = stringFlag(context, "beacon");
+    if (path === undefined) {
+        return undefined;
+    }
+    const exports = await loadProjectModule(context.cwd, path);
+    return pickExport(exports, path, "beacon", isStore, "beacon store (`{ read(namespace), create(namespace, value) }`)");
+};
+/**
+ * The namespace's own beacon, its row written the first time; a row the registry
+ * does not hold (`registered`) is refused, never adopted (`ensureBeacon`).
+ */
+export const ownBeacon = async (store, namespace, registered) => {
+    try {
+        return (await ensureBeacon(store, namespace, registered)).value;
+    }
+    catch (error) {
+        throw new CliFailure(codeOf(error) === undefined ? EXIT_ERROR : EXIT_FAILED, `namespace "${namespace}"'s own beacon could not be read or written through the --beacon store (${messageOf(error)})`, codeOf(error));
+    }
+};
+/**
+ * `owner`'s beacon as the store's connection reads it. No row, or a row that holds
+ * no beacon, is refused here: the service does not reach `owner`'s database, and the
+ * registry would refuse the push for it.
+ */
+export const readOwnerBeacon = async (store, owner) => {
+    let value;
+    try {
+        value = await store.read(owner);
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, `reading namespace "${owner}"'s row in ${BEACON_TABLE} through the --beacon store failed (${messageOf(error)})`);
+    }
+    if (value === null || value === undefined) {
+        throw new CliFailure(EXIT_FAILED, `the rules read namespace "${owner}"'s Resources as foreign, and the --beacon store's connection reads no row of "${owner}" in ${BEACON_TABLE}: this service does not reach "${owner}"'s database. A foreign Resource is read only within one database; across databases, carry the fact in a JWT claim instead (\`policies.claims\`)`, "ACCESS_FOREIGN_CROSS_DATABASE");
+    }
+    if (!isBeacon(value)) {
+        throw new CliFailure(EXIT_FAILED, `namespace "${owner}"'s row in ${BEACON_TABLE} holds no beacon (avb_ and 43 base64url characters): it was changed outside the service that writes it`, "ACCESS_BEACON_MISMATCH");
+    }
+    return value;
+};
+/**
+ * Holds `owner`'s beacon, as the store reads it, to the hash `owner` pushed (`null`:
+ * none): the pull's check that this service reaches `owner`'s database.
+ */
+export const holdOwnerBeacon = async (store, owner, pushed) => {
+    if (pushed === null) {
+        throw new CliFailure(EXIT_FAILED, `the rules read namespace "${owner}"'s Resources as foreign, and "${owner}" has pushed no beacon, so nothing shows the two services share a database: "${owner}"'s service pushes its file with \`avaccess push --beacon <module>\` first. Nothing was written`, "ACCESS_FOREIGN_CROSS_DATABASE");
+    }
+    const read = await readOwnerBeacon(store, owner);
+    if ((await beaconHashOf(owner, read)) !== pushed) {
+        throw new CliFailure(EXIT_FAILED, `namespace "${owner}"'s beacon, as the --beacon store's connection reads it, is not the one "${owner}" pushed: this service and "${owner}" are on different databases. A foreign Resource is read only within one database; across databases, carry the fact in a JWT claim instead (\`policies.claims\`). Nothing was written`, "ACCESS_FOREIGN_CROSS_DATABASE");
+    }
+};

package/dist/cli/cli.context.d.ts

@@ -0,0 +1,49 @@
+/** The command did what it says. */
+export declare const EXIT_OK = 0;
+/** It ran, and the answer is no. */
+export declare const EXIT_FAILED = 1;
+/** It could not run. */
+export declare const EXIT_ERROR = 2;
+export type ExitCode = typeof EXIT_OK | typeof EXIT_FAILED | typeof EXIT_ERROR;
+/** A command's refusal: the exit code, the message, and the error code when Access or the registry named one. */
+export declare class CliFailure extends Error {
+    readonly exitCode: typeof EXIT_FAILED | typeof EXIT_ERROR;
+    readonly code: string | undefined;
+    constructor(exitCode: typeof EXIT_FAILED | typeof EXIT_ERROR, message: string, code?: string);
+}
+/** The flags a command reads, parsed. */
+export type CliFlags = {
+    readonly [name: string]: string | boolean | readonly (string | boolean)[] | undefined;
+};
+export type CliContext = {
+    /** The project's directory: the lock and the pulled files are read and written under it. */
+    readonly cwd: string;
+    readonly env: {
+        readonly [name: string]: string | undefined;
+    };
+    readonly flags: CliFlags;
+    readonly positionals: readonly string[];
+    /** Writes one line to standard output. */
+    out(line: string): void;
+    /**
+     * Resolves, with the signal's name, once the process is told to stop (SIGTERM or
+     * SIGINT). Only a command that runs until stopped (`serve`) calls it; the bin
+     * listens for the signals from that call on.
+     */
+    untilStopped(): Promise<string>;
+};
+/** A string flag's value, or `undefined`. */
+export declare const stringFlag: (context: CliContext, name: string) => string | undefined;
+/** The command's positional arguments, refused when there are more or fewer than it takes. */
+export declare const positionals: (context: CliContext, usage: string, min: number, max: number) => readonly string[];
+/**
+ * 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 declare const projectFilePath: (value: string, flag: string, example: string, extension: string) => string;
+/** The version of `@aventara/access` this bin is, from its own manifest. */
+export declare const versionOf: () => Promise<string>;
+/** An error's message without the package's prefix: the CLI names itself. */
+export declare const messageOf: (error: unknown) => string;
+/** The `code` an Access error carries (read by shape: a module the CLI loads may hold its own copy of Access). */
+export declare const codeOf: (error: unknown) => string | undefined;

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>;