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

package/dist/better-auth/organization.bridge.js

@@ -0,0 +1,144 @@
+// The organization bridge (`aventaraAccess({ organization })`): a member's role in
+// Better Auth's organization plugin becomes two claims of the token, the role's
+// mapped value and the organization it holds in, so the rules read it as an
+// organization's role, never a global one. Both are read when the token is issued,
+// from the membership Better Auth's store holds for the session's active
+// organization: removing the member, or changing their role, changes the next token.
+//
+// An organization role is a fact about one organization. The rules' grammar has no
+// role held "in the active organization", so the bridge hands the rules the
+// organization beside the role, and each grant on the role must be held to it
+// (`where: { organizationId: me.org }`, with `principal` copying the claim onto
+// `me`). A rule on the role alone grants across every organization: the README says
+// so, and the bridge's own refusals keep the role from being self-made.
+//
+// The bridge trusts the organization plugin's memberships, so it refuses an
+// organization plugin
+// - whose invitations a user with an unverified email may accept (GHSA-fmh4-wcc4-5jm3);
+// - that lets any user create an organization, and so make themselves its owner,
+//   unless the app chose that (`allowUserToCreateOrganization` `false`, or a function);
+// - with dynamic access control, mapping a role that is not one of its static roles
+//   (an organization's admins name dynamic roles).
+import { AccessError } from "../access/access.error.js";
+import { organizationPluginOf, refuseUnverifiedInvitations, } from "../access/better-auth.hardening.js";
+import { isRecord } from "../policies.compiler.js";
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+const SHAPE = '`organization` is `{ claim, organizationClaim, roles }`: the claim a member\'s role fills and the claim its organization fills (both declared as "string" in `policies.claims`), and each Better Auth role, in order, with its value: `[["owner", "admin"], ["admin", "admin"]]`';
+/** A role name Better Auth stores as one: not empty, no comma, no whitespace. */
+const ROLE_NAME = /^[^\s,]+$/;
+/** One of the two claims, checked: declared as a string. */
+const stringClaim = (member, claim, claims) => {
+    if (typeof claim !== "string" || claims[claim] !== "string") {
+        return refuse(`${SHAPE}; \`organization.${member}\` names ${typeof claim === "string" ? (claims[claim] === undefined ? `the claim "${claim}", which \`policies.claims\` does not declare` : `\`${claim}\`, which \`policies.claims\` declares as ${claims[claim]}`) : JSON.stringify(claim)}.`);
+    }
+    return claim;
+};
+/** The `organization` option, checked against the declared claims; `undefined` when it is not given. */
+export const checkBridge = (value, claims) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return refuse(`${SHAPE}.`);
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== "claim" && key !== "organizationClaim" && key !== "roles") {
+            refuse(`${SHAPE}; it does not take \`${key}\`.`);
+        }
+    }
+    const claim = stringClaim("claim", value.claim, claims);
+    const organizationClaim = stringClaim("organizationClaim", value.organizationClaim, claims);
+    if (claim === organizationClaim) {
+        refuse(`${SHAPE}; \`claim\` and \`organizationClaim\` are both "${claim}": they are two claims.`);
+    }
+    const { roles } = value;
+    if (!Array.isArray(roles) || roles.length === 0) {
+        return refuse(`${SHAPE}; \`organization.roles\` is ${Array.isArray(roles) ? "empty" : JSON.stringify(roles)}.`);
+    }
+    const entries = [];
+    const seen = [];
+    for (const entry of roles) {
+        const [role, mapped] = Array.isArray(entry) ? entry : [];
+        if (!Array.isArray(entry) ||
+            entry.length !== 2 ||
+            typeof role !== "string" ||
+            !ROLE_NAME.test(role) ||
+            seen.includes(role) ||
+            typeof mapped !== "string" ||
+            mapped === "") {
+            return refuse(`${SHAPE}; \`organization.roles\` holds ${JSON.stringify(entry)}: each entry is a Better Auth role (one name, no comma or whitespace, listed once) and a value.`);
+        }
+        seen.push(role);
+        entries.push([role, mapped]);
+    }
+    return { claim, organizationClaim, roles: entries };
+};
+/** Better Auth's organization roles when the app names none of its own. */
+const DEFAULT_ROLES = ["owner", "admin", "member"];
+/**
+ * Refuses a bridge over Better Auth without its organization plugin, and over one
+ * that lets a member be made otherwise than the app decided: by an unverified email
+ * accepting an invitation, by any user creating an organization, or (with dynamic
+ * access control) under a role an organization's admins name.
+ */
+export const checkBridgePlugins = (plugins, bridge) => {
+    const organization = organizationPluginOf(plugins);
+    if (organization === undefined) {
+        throw new AccessError("ACCESS_RESOURCE_MISSING", "`aventaraAccess({ organization })` reads Better Auth's organization memberships, and Better Auth has no organization plugin: add organization() to plugins.");
+    }
+    refuseUnverifiedInvitations(plugins, "`aventaraAccess({ organization })`");
+    const { allowUserToCreateOrganization, dynamicAccessControl, roles } = organization.options;
+    if (allowUserToCreateOrganization !== false &&
+        typeof allowUserToCreateOrganization !== "function") {
+        refuse("`aventaraAccess({ organization })` maps an organization's roles into claims, and the organization plugin lets any user create an organization, and so be its owner. Decide who may: pass `organization({ allowUserToCreateOrganization: false })`, or a function of the user.");
+    }
+    if (isRecord(dynamicAccessControl) && dynamicAccessControl.enabled === true) {
+        const statics = isRecord(roles) ? Object.keys(roles) : DEFAULT_ROLES;
+        for (const [role] of bridge.roles) {
+            if (!statics.includes(role)) {
+                refuse(`\`aventaraAccess({ organization })\` maps the role "${role}", and with dynamic access control an organization's admins name roles themselves: map only the organization plugin's static roles (${statics.join(", ")}).`);
+            }
+        }
+    }
+};
+/**
+ * The bridged claims for a session: the mapped value of the member's role in the
+ * session's active organization, and that organization's id, read from Better Auth's
+ * store; `undefined` when there is no active organization, no membership, or no role
+ * the bridge maps. The member's roles are read as Better Auth reads them, split on
+ * `,` and taken as they are: a stored role with whitespace in it (`member, owner`) is
+ * one Better Auth does not grant, and gives nothing here.
+ */
+export const bridgedClaims = async (bridge, context, source) => {
+    const organizationId = source.session.activeOrganizationId;
+    if (typeof organizationId !== "string" || organizationId === "") {
+        return undefined;
+    }
+    const member = await context.adapter.findOne({
+        model: "member",
+        where: [
+            { field: "userId", value: source.user.id },
+            { field: "organizationId", value: organizationId },
+        ],
+    });
+    if (typeof member?.role !== "string") {
+        return undefined;
+    }
+    const held = member.role.split(",");
+    for (const role of held) {
+        if (!ROLE_NAME.test(role)) {
+            return undefined;
+        }
+    }
+    for (const [role, value] of bridge.roles) {
+        if (held.includes(role)) {
+            return {
+                [bridge.claim]: value,
+                [bridge.organizationClaim]: organizationId,
+            };
+        }
+    }
+    return undefined;
+};

package/dist/canonical-json.writer.d.ts

@@ -0,0 +1,12 @@
+/** A JSON value, as the canonical writer reads it. */
+export type CanonicalJson = string | number | boolean | null | readonly CanonicalJson[] | {
+    readonly [key: string]: CanonicalJson | undefined;
+};
+/** JSON text with every object's members sorted by key and no whitespace. */
+export declare const canonicalJson: (value: CanonicalJson) => string;
+/** A copy of a list of names, sorted: the order of a list the format calls a set. */
+export declare const sortedNames: <T extends string>(list: readonly T[]) => T[];
+/** Orders rules by their `id`. */
+export declare const byId: <T extends {
+    readonly id: string;
+}>(a: T, b: T) => number;

package/dist/canonical-json.writer.js

@@ -0,0 +1,30 @@
+// The canonical JSON text both Access file formats hash (`policies.hash.ts`,
+// `guardrails/guardrails.hash.ts`): every object's members sorted by key (UTF-16
+// code units), whitespace removed, members whose value is `undefined` left out, and
+// strings and numbers written as `JSON.stringify` writes them (RFC 8785's rules for
+// the values these files hold). A number JSON cannot carry (NaN, Infinity) throws. Which lists a format treats as sets is the format's
+// own decision; this writer keeps every list in the order it is given.
+/** JSON text with every object's members sorted by key and no whitespace. */
+export const canonicalJson = (value) => {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        // `JSON.stringify` writes NaN and Infinity as `null`: two files that decide
+        // differently would share one hash.
+        throw new Error(`Aventara Access: a file holds the number ${value}, and JSON carries finite numbers only`);
+    }
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const record = value;
+    const members = Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+    return `{${members.join(",")}}`;
+};
+/** A copy of a list of names, sorted: the order of a list the format calls a set. */
+export const sortedNames = (list) => [...list].sort();
+/** Orders rules by their `id`. */
+export const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;

package/dist/cli/avaccess.bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/avaccess.bin.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// The `avaccess` bin. It runs the program in the working directory, waits for its
+// lines to reach the terminal or the pipe, and exits with its code: a command that
+// loaded the Access server's module (`keys`) may leave a database pool open, and
+// the bin does not wait for it. A command that runs until stopped (`serve`) stops on
+// SIGTERM or SIGINT; the bin listens for them only once such a command asks.
+import process from "node:process";
+import { runAvaccess } from "./avaccess.program.js";
+const flushed = () => new Promise((resolve) => {
+    process.stdout.write("", () => {
+        process.stderr.write("", () => resolve());
+    });
+});
+const code = await runAvaccess(process.argv.slice(2), process.cwd(), process.env, {
+    out: (line) => {
+        process.stdout.write(`${line}\n`);
+    },
+    err: (line) => {
+        process.stderr.write(`${line}\n`);
+    },
+}, () => new Promise((resolve) => {
+    process.once("SIGTERM", () => resolve("SIGTERM"));
+    process.once("SIGINT", () => resolve("SIGINT"));
+}));
+await flushed();
+process.exit(code);

package/dist/cli/avaccess.program.d.ts

@@ -0,0 +1,15 @@
+import { type ExitCode } from "./cli.context.js";
+/** What the program prints and where. */
+type ProgramOutput = {
+    out(line: string): void;
+    err(line: string): void;
+};
+/**
+ * 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 declare const runAvaccess: (args: readonly string[], cwd: string, env: {
+    readonly [name: string]: string | undefined;
+}, printed: ProgramOutput, untilStopped?: () => Promise<string>) => Promise<ExitCode>;
+export {};

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;