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

package/dist/cli/keys.command.js

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

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

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

package/dist/cli/lock.file.js

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

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

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

package/dist/cli/module.loader.js

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

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

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

package/dist/cli/policies.diff.js

@@ -0,0 +1,83 @@
+// What changed between two revisions of a namespace's policies file, by name: each
+// grant and deny by its `id`, each role by its name, each governed Resource, each
+// schema entry and each claim. Both files are compared in their canonical form
+// (`policies.hash.ts`), so a reordering is no change, and a changed entry lists the
+// members that differ.
+import { canonicalJson } from "../canonical-json.writer.js";
+import { canonicalPolicies } from "../policies.hash.js";
+/** A file's members in canonical form. */
+const canonicalOf = (file) => JSON.parse(canonicalPolicies(file));
+const text = (value) => value === undefined ? "" : canonicalJson(value);
+/** The members of two entries that differ (none when either is not an object). */
+const differingMembers = (before, after) => {
+    if (typeof before !== "object" ||
+        typeof after !== "object" ||
+        before === null ||
+        after === null ||
+        Array.isArray(before) ||
+        Array.isArray(after)) {
+        return [];
+    }
+    const a = before;
+    const b = after;
+    return [...new Set([...Object.keys(a), ...Object.keys(b)])]
+        .filter((key) => text(a[key]) !== text(b[key]))
+        .sort();
+};
+const compareEntries = (part, before, after) => {
+    const changes = [];
+    for (const name of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+        const a = before.get(name);
+        const b = after.get(name);
+        if (a === undefined) {
+            changes.push({ part, name, change: "added" });
+        }
+        else if (b === undefined) {
+            changes.push({ part, name, change: "removed" });
+        }
+        else if (text(a) !== text(b)) {
+            const members = differingMembers(a, b);
+            changes.push({
+                part,
+                name,
+                change: "changed",
+                ...(members.length > 0 ? { members } : {}),
+            });
+        }
+    }
+    return changes;
+};
+const byKey = (record) => new Map(Object.entries((record ?? {})).filter(([, value]) => value !== undefined));
+const byId = (rules) => new Map((rules ?? []).map((rule) => [
+    String(rule.id),
+    rule,
+]));
+/** The named changes from `before` to `after`, in the order of the file's parts. */
+export const diffPolicies = (before, after) => {
+    const a = canonicalOf(before);
+    const b = canonicalOf(after);
+    const namespace = text(a.namespace) === text(b.namespace)
+        ? []
+        : [
+            {
+                part: "namespace",
+                name: String(b.namespace ?? a.namespace),
+                change: a.namespace === undefined
+                    ? "added"
+                    : b.namespace === undefined
+                        ? "removed"
+                        : "changed",
+            },
+        ];
+    return [
+        ...namespace,
+        ...compareEntries("claim", byKey(a.claims), byKey(b.claims)),
+        ...compareEntries("schema", byKey(a.schema), byKey(b.schema)),
+        ...compareEntries("role", byKey(a.roles), byKey(b.roles)),
+        ...compareEntries("govern", byKey(a.govern), byKey(b.govern)),
+        ...compareEntries("grant", byId(a.grants), byId(b.grants)),
+        ...compareEntries("deny", byId(a.denies), byId(b.denies)),
+    ];
+};
+/** A change as one line: `grant "Note/read/player#1": changed (where)`. */
+export const changeLine = (change) => `${change.part} ${JSON.stringify(change.name)}: ${change.change}${change.members === undefined ? "" : ` (${change.members.join(", ")})`}`;

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

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