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

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

package/dist/cli/verify.command.js

@@ -0,0 +1,40 @@
+// `avaccess verify`: the pulled files on disk against `avAccess.lock.json`, offline.
+// It reads the lock and the files it pins and runs the engine's own check
+// (`lock.verifier.ts`): no registry, no network. It belongs at the front of a
+// project's `aventara:prepare` script, so a pulled file edited by hand stops the
+// build before anything is generated from it.
+import { foreignOwnersOf, verifyLocked } from "../lock/lock.verifier.js";
+import { LOCK_FILE } from "../lock/lock-contract.js";
+import { environmentOf, verifyBeaconPins } from "./beacon-pins.file.js";
+import { CliFailure, codeOf, EXIT_FAILED, EXIT_OK, messageOf, positionals, } from "./cli.context.js";
+import { readForeignPinned, readLock, readPinned } from "./lock.file.js";
+export const verifyCommand = async (context) => {
+    positionals(context, "avaccess verify [--env <environment>]", 0, 0);
+    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);
+    try {
+        verifyLocked(lock, {
+            namespace: policies
+                ?.namespace,
+            policies,
+            guardrails,
+        });
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_FAILED, messageOf(error), codeOf(error));
+    }
+    await readForeignPinned(context.cwd, lock);
+    const owners = foreignOwnersOf(policies);
+    const environments = await verifyBeaconPins(context.cwd, lock.namespace, owners, environmentOf(context));
+    context.out(`verified against ${LOCK_FILE}: ${lock.policies.path} (${lock.policies.hash})${lock.guardrails === null
+        ? ", and no guardrails pinned"
+        : ` and ${lock.guardrails.path} (${lock.guardrails.hash})`}${lock.foreign === undefined
+        ? ""
+        : `, and the foreign facts ${lock.foreign.path} (${lock.foreign.hash})`}${environments.length === 0
+        ? ""
+        : `; the beacon pins of ${environments.map((environment) => `"${environment}"`).join(", ")} cover what the rules read`}`);
+    return EXIT_OK;
+};

package/dist/client/access-client.factory.d.ts

@@ -0,0 +1,92 @@
+import type { AccessClaimsDeclaration } from "../access/claims.mapper.js";
+import { type AccessProfileKind } from "../access/profile.policy.js";
+import type { SignInIdentifier } from "../audit/audit.log.js";
+import { type AccessKioskVerbName } from "../kiosk/kiosk-verbs.schema.js";
+import { type AccessVerbSchema } from "./access-verbs.schema.js";
+import type { LimitedCall, LimitSettle } from "./verb-rate.limiter.js";
+/** The headers of a request, as the framework hands them to `call`. */
+type RequestHeaders = {
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callback: (value: string, name: string) => void): void;
+};
+/** One verb as `access.client` publishes it: its route, its shapes and its server call. */
+type AccessClientVerb = {
+    readonly method: "GET" | "POST";
+    readonly path: string;
+    readonly args?: AccessVerbSchema;
+    readonly result: AccessVerbSchema;
+    call(input: {
+        readonly args: unknown;
+        readonly headers: RequestHeaders;
+        readonly request?: unknown;
+    }): Promise<unknown>;
+};
+/** The verbs `access.client` publishes: each one the instance serves. */
+type AccessClientVerbs = {
+    signIn?: AccessClientVerb;
+    signUp?: AccessClientVerb;
+    signOut?: AccessClientVerb;
+    resetPassword?: AccessClientVerb;
+    me?: AccessClientVerb;
+} & {
+    [V in AccessKioskVerbName]?: AccessClientVerb;
+};
+/** `access.client`. */
+type AccessClient = {
+    readonly url: string;
+    readonly verbs: Readonly<AccessClientVerbs>;
+};
+/** Better Auth's refusal, as `call` throws one: a status, and a sentence. */
+/** A refusal's body: Better Auth's `{ message, code }`. */
+type RefusalBody = {
+    readonly message?: unknown;
+    readonly code?: unknown;
+};
+type RefusalError = new (status: string | number, body: RefusalBody, headers?: {
+    readonly [name: string]: string;
+}) => Error;
+/**
+ * Builds `access.client` for an instance: from its Better Auth options (`baseURL`,
+ * `basePath`, `emailAndPassword`, `disabledPaths`), its profile and its declared
+ * claims.
+ */
+export declare const accessClient: (input: {
+    readonly block: {
+        readonly [key: string]: unknown;
+    };
+    readonly kind: AccessProfileKind;
+    readonly claims: AccessClaimsDeclaration;
+    /** Better Auth's base URL resolution, as `getBaseURL` resolves it. */
+    readonly baseOf: (baseURL: string | undefined, basePath: string | undefined) => string | undefined;
+    readonly isDynamicBaseURL: (baseURL: unknown) => boolean;
+    /** Better Auth's server API, built on first use. */
+    readonly api: () => unknown;
+    /** The request's identity, as `access.state` reads it. */
+    readonly identityOf: (headers: RequestHeaders, request: unknown) => Promise<unknown>;
+    /** Where `call` registers the requests it builds, for the Access plugin's origin check. */
+    readonly calls: WeakSet<object>;
+    readonly refusal: RefusalError;
+    /** How the sign-in route reads its identifier from a body (`email:<address>`). */
+    readonly identify: SignInIdentifier;
+    /** The rate limit on `signIn`, `signUp` and `resetPassword`: throws Better Auth's 429, else answers what clears the target's count once the call succeeds. */
+    readonly limit: (call: LimitedCall) => Promise<LimitSettle | undefined>;
+    /** Better Auth's context, once Better Auth is built: its plugins' `onRequest` hooks run with it. */
+    readonly context: () => Promise<unknown>;
+}) => AccessClient;
+/** Better Auth's `createAuthEndpoint`, as Access's `me` route calls it. */
+export type MeEndpointFactory = (path: string, options: {
+    readonly method: "GET";
+}, handler: (context: {
+    readonly headers?: Headers | undefined;
+    readonly request?: unknown;
+}) => Promise<Response>) => unknown;
+/**
+ * Access's `GET /me` route (under Better Auth's base path), keyed as Better Auth keys
+ * a plugin's endpoints (`access.api.accessMe`): the request's identity, `{ sub,
+ * claims }`, or `null`, as `access.client.verbs.me.call` answers it. Never cached.
+ */
+export declare const meEndpoint: (endpoint: MeEndpointFactory, identityOf: (headers: RequestHeaders, request: unknown) => Promise<unknown>) => {
+    accessMe: unknown;
+};
+export {};