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

package/dist/cli/registry.client.js

@@ -0,0 +1,287 @@
+// The registry, as `avaccess` reaches it: its read-only routes and its push route,
+// over HTTP, with the namespace's key in the `x-access-key` header. The CLI stores
+// nothing of its own; every answer is the registry's. A revision's file is hashed
+// again here, so a file is never written or compared under a hash it does not have.
+//
+// The registry's address is `--registry` or `AVACCESS_REGISTRY_URL`: the Access
+// server's URL, with Better Auth's base path the way Better Auth's own client reads
+// it (a URL with no path gets `/api/auth`). It is `https:`, or `http:` on a loopback
+// address only, since the key travels in a header. The key is `AVACCESS_KEY` only,
+// never a flag, so it stays out of shell history and process lists, and no line the
+// CLI prints quotes it. The CLI follows no redirect: a key goes to the address it
+// was given and nowhere else. What the registry answers is data: a file is held to
+// its hash and to the namespace asked for, and its text is printed without the
+// control characters a terminal would act on.
+import { guardrailsHash } from "../guardrails/guardrails.hash.js";
+import { isNamespace } from "../policies.compiler.js";
+import { policiesHash } from "../policies.hash.js";
+import { KEY_HEADER, KEY_OWNER_PATH, REGISTRY_PATH, } from "../registry/registry.endpoints.js";
+import { CliFailure, EXIT_ERROR, EXIT_FAILED, messageOf, stringFlag, } from "./cli.context.js";
+/** The environment variable that holds the registry's URL, when `--registry` does not. */
+export const REGISTRY_URL_VARIABLE = "AVACCESS_REGISTRY_URL";
+/** The environment variable that holds the namespace's key. */
+export const KEY_VARIABLE = "AVACCESS_KEY";
+/** Better Auth's default base path, added to a URL that has none. */
+const DEFAULT_BASE_PATH = "/api/auth";
+/** A revision's hash, as the registry names it. */
+const HASH = /^sha256:[0-9a-f]{64}$/;
+/**
+ * The characters a terminal may act on or that change how the text around them
+ * reads: the control characters (`Cc`, U+0000 to U+001F and U+007F to U+009F), the
+ * format characters (`Cf`: bidirectional overrides and isolates such as U+202E and
+ * U+2066, zero-width ones, U+FEFF), the line and paragraph separators (U+2028,
+ * U+2029) and lone surrogates.
+ */
+const CONTROL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/gu;
+/** Text the registry sent, as the CLI prints it: none of those characters, at most 2,000 characters. */
+const printable = (text) => {
+    const plain = text.replace(CONTROL, " ");
+    return plain.length > 2_000 ? `${plain.slice(0, 2_000)}…` : plain;
+};
+/** Whether a URL's host is a loopback address: `localhost`, 127.0.0.0/8 or `::1`. */
+const isLoopback = (url) => url.hostname === "localhost" ||
+    url.hostname === "[::1]" ||
+    /^127\.(?:\d{1,3})\.(?:\d{1,3})\.(?:\d{1,3})$/.test(url.hostname);
+/** The registry's base URL: the Access server's URL and Better Auth's base path. */
+const baseUrlOf = (context) => {
+    const given = stringFlag(context, "registry") ?? context.env[REGISTRY_URL_VARIABLE];
+    if (given === undefined || given === "") {
+        throw new CliFailure(EXIT_ERROR, `no registry: pass --registry <url> or set ${REGISTRY_URL_VARIABLE} to the Access server's URL (such as https://access.example.com)`);
+    }
+    let url;
+    try {
+        url = new URL(given);
+    }
+    catch {
+        throw new CliFailure(EXIT_ERROR, `the registry's URL ${JSON.stringify(given)} is not a URL`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new CliFailure(EXIT_ERROR, `the registry's URL is http or https; it was ${url.protocol}`);
+    }
+    if (url.protocol === "http:" && !isLoopback(url)) {
+        throw new CliFailure(EXIT_ERROR, `the registry's URL ${url.origin} is http:, which sends the key in the clear: use its https: URL (http: is taken only on a loopback address: localhost, 127.0.0.0/8 or [::1])`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new CliFailure(EXIT_ERROR, "the registry's URL holds a user name or password; the registry takes its key in AVACCESS_KEY only");
+    }
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${path === "" ? DEFAULT_BASE_PATH : path}`;
+};
+const keyOf = (context) => {
+    const key = context.env[KEY_VARIABLE];
+    if (key === undefined || key === "") {
+        throw new CliFailure(EXIT_ERROR, `no registry key: set ${KEY_VARIABLE} to the namespace's key (its pull key, or its push key to push)`);
+    }
+    return key;
+};
+/** The registry the context names, with its key. */
+export const registryClient = (context) => {
+    const base = baseUrlOf(context);
+    const key = keyOf(context);
+    /** One call; a refusal names the registry's code and message, never the key. */
+    const call = async (method, path, body, under = REGISTRY_PATH) => {
+        const url = `${base}${under}${path}`;
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                // A redirect is answered, never followed: following it would send the
+                // key, and a push's file, to the address it names.
+                redirect: "manual",
+                headers: {
+                    [KEY_HEADER]: key,
+                    accept: "application/json",
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+        }
+        catch (error) {
+            throw new CliFailure(EXIT_ERROR, `the registry at ${base} did not answer (${messageOf(error.cause ?? error)})`);
+        }
+        if (response.type === "opaqueredirect" ||
+            (response.status >= 300 && response.status < 400)) {
+            const location = response.headers.get("location");
+            throw new CliFailure(EXIT_ERROR, `the registry at ${base} answered ${response.status}, a redirect${location === null ? "" : ` to ${printable(location)}`}. avaccess follows no redirect, so the key is sent to no other address: set --registry or ${REGISTRY_URL_VARIABLE} to the registry's own URL`);
+        }
+        const text = await response.text();
+        let json;
+        try {
+            json = text === "" ? null : JSON.parse(text);
+        }
+        catch {
+            json = undefined;
+        }
+        if (response.status === 404 &&
+            typeof json?.code !== "string") {
+            throw new CliFailure(EXIT_ERROR, `${base} serves no registry: is it the Access server's URL, with the registry on (\`registry: { enabled: true }\`)?`);
+        }
+        return { status: response.status, json };
+    };
+    const refused = (answer) => {
+        const body = (answer.json ?? {});
+        const code = typeof body.code === "string" ? printable(body.code) : undefined;
+        const message = typeof body.message === "string"
+            ? printable(messageOf(body.message))
+            : `the registry answered ${answer.status}`;
+        throw new CliFailure(answer.status >= 500 ? EXIT_ERROR : EXIT_FAILED, message, code);
+    };
+    const segment = (text) => encodeURIComponent(text);
+    const hashed = (json, hash, what) => {
+        const revision = json;
+        let found;
+        try {
+            found = hash(revision.file);
+        }
+        catch (error) {
+            throw new CliFailure(EXIT_FAILED, `the registry served ${what} that is no file the engine runs from (${printable(messageOf(error))})`);
+        }
+        if (found !== revision.hash) {
+            throw new CliFailure(EXIT_FAILED, `the registry served ${what} under ${printable(String(revision.hash))}, and it hashes to ${found}`);
+        }
+        return { hash: found, file: revision.file };
+    };
+    /** A namespace's file, held to the namespace it was asked for. */
+    const namespaced = (pulled, namespace, what) => {
+        if (pulled.file.namespace !== namespace) {
+            throw new CliFailure(EXIT_FAILED, `the registry served ${what} as a file of ${pulled.file.namespace === undefined
+                ? "no namespace"
+                : `namespace ${JSON.stringify(pulled.file.namespace)}`}: a namespace's revision is its own file. Nothing was written`);
+        }
+        return pulled;
+    };
+    /** A hash the registry named, checked to be one. */
+    const hashNamed = (value, what) => {
+        if (typeof value !== "string" || !HASH.test(value)) {
+            throw new CliFailure(EXIT_FAILED, `the registry named ${what} with no sha256 hash`);
+        }
+        return value;
+    };
+    return {
+        url: base,
+        /** The namespace the key belongs to, as the registry names it. */
+        keyNamespace: async () => {
+            const answer = await call("GET", "", undefined, KEY_OWNER_PATH);
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            const namespace = answer.json
+                ?.namespace;
+            if (!isNamespace(namespace)) {
+                throw new CliFailure(EXIT_FAILED, "the registry did not name the key's namespace");
+            }
+            return namespace;
+        },
+        /** The hash of the namespace's current beacon (`null`: it has pushed none). */
+        namespaceBeacon: async (namespace) => {
+            const answer = await call("GET", `/${segment(namespace)}`);
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            const beacon = answer.json
+                ?.beacon;
+            return beacon === null || beacon === undefined
+                ? null
+                : hashNamed(beacon, `namespace "${namespace}"'s beacon`);
+        },
+        /** The namespace's current revision's hash (`null`: nothing pushed yet). */
+        headHash: async (namespace) => {
+            const answer = await call("GET", `/${segment(namespace)}`);
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            const head = answer.json?.head;
+            return head === null || head === undefined
+                ? null
+                : hashNamed(head, `namespace "${namespace}"'s head`);
+        },
+        /** The namespace's current revision, with its file. */
+        head: async (namespace) => {
+            const answer = await call("GET", `/${segment(namespace)}/head`);
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            return namespaced(hashed(answer.json, policiesHash, `namespace "${namespace}"'s head`), namespace, `namespace "${namespace}"'s head`);
+        },
+        /** One of the namespace's revisions, with its file. */
+        revision: async (namespace, hash) => {
+            const answer = await call("GET", `/${segment(namespace)}/revisions/${segment(hash)}`);
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            return namespaced(hashed(answer.json, policiesHash, `revision ${hash}`), namespace, `revision ${hash}`);
+        },
+        /** The namespace's revisions, newest first. */
+        revisions: async (namespace) => {
+            const answer = await call("GET", `/${segment(namespace)}/revisions`);
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            const revisions = answer.json
+                ?.revisions;
+            if (!Array.isArray(revisions)) {
+                throw new CliFailure(EXIT_FAILED, `the registry did not list namespace "${namespace}"'s revisions`);
+            }
+            return revisions.map((entry) => ({
+                hash: hashNamed(entry?.hash, `a revision of namespace "${namespace}"`),
+                createdAt: printable(String(entry?.createdAt ?? "")),
+            }));
+        },
+        /** The org's current guardrails, with their file (`null`: none pushed yet). */
+        guardrails: async (namespace) => {
+            const answer = await call("GET", `/${segment(namespace)}/guardrails`);
+            if (answer.status === 404) {
+                return null;
+            }
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            return hashed(answer.json, guardrailsHash, "the org's guardrails");
+        },
+        /**
+         * What `namespace` reads of `owner` as foreign: the hash of `owner`'s beacon,
+         * and its schema entry of each of `resources`. Each entry is the owner's own,
+         * for a Resource asked for; anything else is refused.
+         */
+        foreign: async (namespace, owner, resources) => {
+            const query = resources.length === 0
+                ? ""
+                : `?resources=${resources.map(segment).join(",")}`;
+            const answer = await call("GET", `/${segment(namespace)}/foreign/${segment(owner)}${query}`);
+            if (answer.status !== 200) {
+                return refused(answer);
+            }
+            const body = (answer.json ?? {});
+            const entries = body.resources;
+            if (body.owner !== owner ||
+                (body.beacon !== null &&
+                    (typeof body.beacon !== "string" || !HASH.test(body.beacon))) ||
+                typeof entries !== "object" ||
+                entries === null ||
+                Array.isArray(entries) ||
+                Object.keys(entries).some((name) => !resources.includes(name)) ||
+                resources.some((name) => !Object.hasOwn(entries, name))) {
+                throw new CliFailure(EXIT_FAILED, `the registry answered what namespace "${namespace}" reads of "${owner}" with something else than the beacon's hash and the Resources asked for. Nothing was written`);
+            }
+            return {
+                beacon: body.beacon,
+                resources: entries,
+            };
+        },
+        /**
+         * Pushes the namespace's file, with the beacons its service read when there
+         * are; answers its hash and whether the registry stored it now.
+         */
+        push: async (namespace, file, beacons) => {
+            const answer = await call("POST", `/${segment(namespace)}/revisions`, beacons === undefined ? file : { file, beacons });
+            if (answer.status !== 200 && answer.status !== 201) {
+                return refused(answer);
+            }
+            const pushed = answer.json;
+            return {
+                hash: hashNamed(pushed?.hash, "the pushed revision"),
+                created: pushed?.created === true,
+            };
+        },
+    };
+};

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

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

package/dist/cli/schema.command.js

@@ -0,0 +1,60 @@
+// `avaccess schema --orm <orm> [--schema <path>] [--out <file>]`: the `AccessSchema`
+// of a service that does not run on Aventara, read from its ORM's schema, written as a
+// TypeScript module its rules are authored against with `definePolicies`. An Aventara
+// app authors against its discovered model instead. No network.
+//
+// When `avAccess.lock.json` pins foreign facts (`avaccess pull --foreign`), the
+// Resources they hold are marked as their owners' (`foreign.merger.ts`): the rules
+// read them in conditions, never grant on them. Until they are pulled, a Resource
+// another namespace owns is not in the model as foreign.
+import { resolve } from "node:path";
+import { mergeForeign } from "../foreign/foreign.merger.js";
+import { emitSchemaModule } from "../generator/schema.emitter.js";
+import { CliFailure, EXIT_ERROR, EXIT_OK, messageOf, positionals, projectFilePath, stringFlag, } from "./cli.context.js";
+import { readForeignPinned, readLockIfAny, writeProjectFile, } from "./lock.file.js";
+import { translatorOf } from "./translator.flag.js";
+/** Where the schema module goes when `--out` does not say. */
+const DEFAULT_SCHEMA_MODULE = "src/generated/avAccess.schema.ts";
+export const schemaCommand = async (context) => {
+    positionals(context, "avaccess schema --orm <orm> [--schema <path>] [--out <file>]", 0, 0);
+    const translator = translatorOf(context);
+    const out = projectFilePath(stringFlag(context, "out") ?? DEFAULT_SCHEMA_MODULE, "--out", DEFAULT_SCHEMA_MODULE, ".ts");
+    const source = (stringFlag(context, "schema") ?? translator.defaultSchema).replace(/\\/g, "/");
+    let reading;
+    try {
+        reading = await translator.readSchema(resolve(context.cwd, source));
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, error?.code === "ENOENT"
+            ? `no ${translator.title} schema at ${source}: pass its file or folder with \`--schema <path>\``
+            : `${source} could not be read (${messageOf(error)})`);
+    }
+    const lock = await readLockIfAny(context.cwd);
+    let schema = reading.schema;
+    const skipped = [...reading.skipped];
+    const facts = lock === undefined ? undefined : await readForeignPinned(context.cwd, lock);
+    if (facts !== undefined) {
+        const merged = mergeForeign(schema, facts, source);
+        schema = merged.schema;
+        skipped.push(...merged.skipped);
+    }
+    const resources = Object.keys(schema.resources);
+    if (resources.length === 0) {
+        throw new CliFailure(EXIT_ERROR, `${source} declares no model Access can read${skipped.length === 0 ? "" : ` (left out: ${skipped.join("; ")})`}`);
+    }
+    await writeProjectFile(context.cwd, out, emitSchemaModule({
+        schema,
+        translator,
+        source,
+        command: `avaccess schema --orm ${translator.orm} --schema ${source} --out ${out}`,
+    }));
+    const enums = Object.keys(schema.enums).length;
+    const foreign = resources.filter((resource) => schema.resources[resource]?.foreign !== undefined);
+    context.out(`wrote ${out}: ${resources.length} Resource${resources.length === 1 ? "" : "s"} (${resources.join(", ")}) and ${enums} enum${enums === 1 ? "" : "s"}, from ${source}${foreign.length === 0
+        ? ""
+        : `; read as foreign: ${foreign.map((resource) => `${resource} (namespace "${schema.resources[resource]?.foreign}")`).join(", ")}`}`);
+    for (const line of skipped) {
+        context.out(`left out: ${line}`);
+    }
+    return EXIT_OK;
+};

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

@@ -0,0 +1,6 @@
+import { type CliContext, type ExitCode } from "./cli.context.js";
+/** The environment variable that asks for the migration on start, as `--migrate` does. */
+export declare const MIGRATE_VARIABLE = "AVACCESS_MIGRATE";
+/** The environment variable read for the port when `--port` is not given. */
+export declare const PORT_VARIABLE = "PORT";
+export declare const serveCommand: (context: CliContext) => Promise<ExitCode>;

package/dist/cli/serve.command.js

@@ -0,0 +1,200 @@
+// `avaccess serve`: the standalone host, run from the operator's configuration. It
+// loads `access.config.ts` (or the file `--config` names) the way `prisma.config.ts`
+// is loaded, with jiti, so the configuration is a TypeScript module with no build
+// step; the module exports the `createAccess({...})` instance, as its default export
+// or as `access`. Then it serves that instance with `serve()` (the same handler, and
+// `GET /health`) until the process is told to stop (SIGTERM or SIGINT).
+//
+// The database: Better Auth's own migration (the plan `npx auth migrate` runs) runs
+// on start only when asked, with `--migrate` or `AVACCESS_MIGRATE=true`. Without it,
+// a database Better Auth can migrate itself (a Kysely-backed one: a `pg` Pool, a
+// MySQL pool, SQLite) is checked first, and a database that lacks tables or columns
+// these options need is refused with what is missing: the host never starts on a
+// schema it would fail on at the first request. A database behind an ORM's adapter
+// (Prisma, Drizzle) is the ORM's to migrate (`npx auth generate`, then the ORM's
+// migration); `--migrate` refuses it.
+//
+// It listens on 127.0.0.1 unless `--hostname` says otherwise (in a container,
+// `0.0.0.0`), and turns Better Auth's rate limit on whatever NODE_ENV is, unless the
+// configuration sets `betterAuth.rateLimit.enabled` itself: Better Auth turns it on
+// in production only, and this is a server facing the network.
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { isRecord } from "../policies.compiler.js";
+import { CliFailure, EXIT_ERROR, EXIT_FAILED, EXIT_OK, messageOf, positionals, stringFlag, } from "./cli.context.js";
+import { loadProjectModule, pickExport } from "./module.loader.js";
+/** The configuration files `avaccess serve` looks for, in this order, when `--config` names none. */
+const CONFIG_FILES = [
+    "access.config.ts",
+    "access.config.mts",
+    "access.config.cts",
+    "access.config.js",
+    "access.config.mjs",
+    "access.config.cjs",
+];
+/** The environment variable that asks for the migration on start, as `--migrate` does. */
+export const MIGRATE_VARIABLE = "AVACCESS_MIGRATE";
+/** The environment variable read for the port when `--port` is not given. */
+export const PORT_VARIABLE = "PORT";
+const USAGE = "avaccess serve [--config <file>] [--port <port>] [--hostname <host>] [--max-body-bytes <bytes>] [--migrate]";
+/** The interface `avaccess serve` listens on when `--hostname` names none: this host only. */
+const DEFAULT_HOSTNAME = "127.0.0.1";
+const isServedInstance = (value) => isRecord(value) &&
+    typeof value.handler === "function" &&
+    isRecord(value.options);
+/** Whether `--migrate` or `AVACCESS_MIGRATE` asks for the migration. */
+const migrateAsked = (context) => {
+    if (context.flags.migrate === true) {
+        return true;
+    }
+    const value = context.env[MIGRATE_VARIABLE];
+    if (value === undefined ||
+        value === "" ||
+        value === "false" ||
+        value === "0") {
+        return false;
+    }
+    if (value === "true" || value === "1") {
+        return true;
+    }
+    throw new CliFailure(EXIT_ERROR, `${MIGRATE_VARIABLE} is "true" or "1" to migrate on start, "false", "0" or unset not to; it was ${JSON.stringify(value)}`);
+};
+const portOf = (context) => {
+    const flag = stringFlag(context, "port");
+    const value = flag ?? context.env[PORT_VARIABLE];
+    if (value === undefined || value === "") {
+        return 3000;
+    }
+    const port = Number(value);
+    if (!/^\d+$/.test(value) || port > 65_535) {
+        throw new CliFailure(EXIT_ERROR, `${flag === undefined ? PORT_VARIABLE : "--port"} is a port number from 0 to 65535; it was ${JSON.stringify(value)}`);
+    }
+    return port;
+};
+const maxBodyOf = (context) => {
+    const value = stringFlag(context, "max-body-bytes");
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!/^\d+$/.test(value) || Number(value) < 1) {
+        throw new CliFailure(EXIT_ERROR, `--max-body-bytes is a number of bytes, 1 or more; it was ${JSON.stringify(value)}`);
+    }
+    return Number(value);
+};
+/**
+ * Turns Better Auth's rate limit on before the instance is built (it is built on
+ * its first request), unless the configuration says whether it is on.
+ */
+const rateLimited = (instance) => {
+    const limit = instance.options.rateLimit;
+    if (limit?.enabled !== undefined) {
+        return;
+    }
+    try {
+        instance.options.rateLimit = { ...limit, enabled: true };
+    }
+    catch {
+        throw new CliFailure(EXIT_ERROR, "Better Auth's options are frozen, so avaccess serve cannot turn its rate limit on: set `betterAuth.rateLimit.enabled` in the configuration (true, unless something in front of it limits the rate)");
+    }
+};
+/** The configuration file: `--config`'s, else the first of `CONFIG_FILES` in the working directory. */
+const configPathOf = async (context) => {
+    const named = stringFlag(context, "config");
+    if (named !== undefined) {
+        return named;
+    }
+    for (const file of CONFIG_FILES) {
+        try {
+            await access(resolve(context.cwd, file));
+            return file;
+        }
+        catch {
+            // Not this one.
+        }
+    }
+    throw new CliFailure(EXIT_ERROR, `no configuration: ${CONFIG_FILES[0]} is not in ${context.cwd}. Write it (its default export is your \`createAccess({...})\` instance), or pass --config <file>`);
+};
+/** The migration's plan, refused when the database is not one Better Auth migrates itself. */
+const planOf = async (instance, migrate) => {
+    const database = instance.options.database;
+    // Better Auth's own migration runs on a Kysely-backed database only; on another
+    // (an ORM's adapter, or none: memory) its planner would end the process.
+    if (database === undefined || typeof database === "function") {
+        if (migrate) {
+            throw new CliFailure(EXIT_ERROR, database === undefined
+                ? "--migrate: the configuration names no `betterAuth.database`, so there is nothing to migrate"
+                : "--migrate: `betterAuth.database` is an ORM's adapter, which Better Auth does not migrate itself. Generate the schema with `npx auth generate` and apply it with the ORM's migration, then start without --migrate");
+        }
+        return undefined;
+    }
+    let migrations;
+    try {
+        migrations = (await import("better-auth/db/migration"));
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, `Better Auth's migration could not be loaded (${messageOf(error)}); install better-auth beside @aventara/access`);
+    }
+    try {
+        return await migrations.getMigrations(instance.options, {
+            throwOnUnsafe: false,
+        });
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, `the database could not be read for Better Auth's migration: ${messageOf(error)}`);
+    }
+};
+/** What the plan would change, one item per table, column and index. */
+const changesOf = (plan) => [
+    ...plan.toBeCreated.map((table) => `table ${table.table}`),
+    ...plan.toBeAdded.flatMap((table) => Object.keys(table.fields).map((field) => `column ${table.table}.${field}`)),
+    ...plan.toBeAddedIndexes.map((index) => `index ${index.name}`),
+];
+export const serveCommand = async (context) => {
+    positionals(context, USAGE, 0, 0);
+    const migrate = migrateAsked(context);
+    const port = portOf(context);
+    const hostname = stringFlag(context, "hostname") ?? DEFAULT_HOSTNAME;
+    const maxBodyBytes = maxBodyOf(context);
+    const config = await configPathOf(context);
+    const instance = pickExport(await loadProjectModule(context.cwd, config), config, "access", isServedInstance, "Access instance (the `createAccess({...})` instance)");
+    const plan = await planOf(instance, migrate);
+    if (plan !== undefined) {
+        if (plan.unsafeChanges.length > 0) {
+            throw new CliFailure(EXIT_FAILED, `Better Auth's migration refuses this database: ${plan.unsafeChanges.join("; ")}`);
+        }
+        const changes = changesOf(plan);
+        if (changes.length > 0 && !migrate) {
+            throw new CliFailure(EXIT_FAILED, `the database lacks what these options need (${changes.join(", ")}). Start once with --migrate (or ${MIGRATE_VARIABLE}=true) to run Better Auth's migration, or run \`npx auth migrate\` against this configuration`);
+        }
+        if (changes.length > 0) {
+            try {
+                await plan.runMigrations();
+            }
+            catch (error) {
+                throw new CliFailure(EXIT_FAILED, `Better Auth's migration failed: ${messageOf(error)}`);
+            }
+            context.out(`migrated: ${changes.join(", ")}`);
+        }
+        else if (migrate) {
+            context.out("migrated: nothing to change");
+        }
+    }
+    rateLimited(instance);
+    const { serve } = await import("../standalone/access.server.js");
+    let server;
+    try {
+        server = await serve(instance, {
+            port,
+            hostname,
+            ...(maxBodyBytes === undefined ? {} : { maxBodyBytes }),
+        });
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_ERROR, `could not listen on ${hostname}, port ${port}: ${messageOf(error)}`);
+    }
+    context.out(`serving ${config} on ${server.url} (health: ${server.url}/health)`);
+    const signal = await context.untilStopped();
+    await server.close();
+    context.out(`stopped (${signal})`);
+    return EXIT_OK;
+};

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

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

package/dist/cli/status.command.js

@@ -0,0 +1,31 @@
+// `avaccess status`: `avAccess.lock.json` against the registry. For each pin (the
+// namespace's policies file, the org's guardrails) it says whether the lock holds the
+// registry's current revision or is behind it, and exits 1 when either is behind,
+// so CI catches a project built with files older than the registry's.
+import { LOCK_FILE } from "../lock/lock-contract.js";
+import { EXIT_FAILED, EXIT_OK, positionals, } from "./cli.context.js";
+import { readLock } from "./lock.file.js";
+import { registryClient } from "./registry.client.js";
+export const statusCommand = async (context) => {
+    positionals(context, "avaccess status", 0, 0);
+    const lock = await readLock(context.cwd);
+    const registry = registryClient(context);
+    const head = await registry.headHash(lock.namespace);
+    const guardrails = await registry.guardrails(lock.namespace);
+    const behind = [];
+    const line = (what, locked, current) => {
+        if (locked === current) {
+            return `${what}: up to date (${locked ?? "none"})`;
+        }
+        behind.push(what);
+        return `${what}: behind: ${LOCK_FILE} pins ${locked ?? "none"}, the registry's current is ${current ?? "none"}`;
+    };
+    context.out(line(`policies of namespace "${lock.namespace}"`, lock.policies.hash, head));
+    context.out(line("the org's guardrails", lock.guardrails?.hash ?? null, guardrails?.hash ?? null));
+    if (behind.length === 0) {
+        context.out(`${LOCK_FILE} is up to date with ${registry.url}`);
+        return EXIT_OK;
+    }
+    context.out(`${LOCK_FILE} is behind the registry (${behind.join("; ")}): run \`avaccess pull\`, then commit the pulled files and the lock`);
+    return EXIT_FAILED;
+};

package/dist/cli/translator.flag.d.ts

@@ -0,0 +1,6 @@
+import { type ClientTranslator, type OrmTranslator } from "../generator/orm.translator.js";
+import { type CliContext } from "./cli.context.js";
+/** `avaccess schema`'s ORM translator: `--orm` is required. */
+export declare const translatorOf: (context: CliContext) => OrmTranslator;
+/** `avaccess generate`'s translator: `--orm`, `none` when it is not given. */
+export declare const clientTranslatorOf: (context: CliContext) => ClientTranslator;

package/dist/cli/translator.flag.js

@@ -0,0 +1,24 @@
+// `--orm <orm>`: which translator `avaccess generate` and `avaccess schema` use.
+// `schema` requires it: there is no neutral schema reader. `generate` defaults to
+// `none` (ruled 2026-10-23), and its banner always spells the value out, so a later
+// translator never changes what an existing script generates.
+import { CLIENT_TRANSLATORS, ORM_TRANSLATORS, } from "../generator/orm.translator.js";
+import { CliFailure, EXIT_ERROR, stringFlag, } from "./cli.context.js";
+/** The translator `--orm` names in `registry`; refused, listing them, when it names none. */
+const translatorIn = (context, registry, fallback) => {
+    const orm = stringFlag(context, "orm") ?? fallback;
+    const known = Object.keys(registry).sort();
+    const translator = orm === undefined || !Object.hasOwn(registry, orm)
+        ? undefined
+        : registry[orm];
+    if (translator === undefined) {
+        throw new CliFailure(EXIT_ERROR, `${orm === undefined
+            ? "pass the ORM with `--orm <orm>`"
+            : `no translator for --orm ${JSON.stringify(orm)}`}; this version has ${known.map((name) => `\`${name}\``).join(", ")}`);
+    }
+    return translator;
+};
+/** `avaccess schema`'s ORM translator: `--orm` is required. */
+export const translatorOf = (context) => translatorIn(context, ORM_TRANSLATORS, undefined);
+/** `avaccess generate`'s translator: `--orm`, `none` when it is not given. */
+export const clientTranslatorOf = (context) => translatorIn(context, CLIENT_TRANSLATORS, "none");

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

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