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

package/dist/cli/policies.diff.js

@@ -0,0 +1,101 @@
+// 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,
+]));
+/**
+ * Each governed Resource as its fields' modes (`"both"` for a field `governModes`
+ * gives none), so a change of mode is named as the field it changes.
+ */
+const governOf = (file) => {
+    const govern = (file.govern ?? {});
+    const modes = (file.governModes ?? {});
+    return new Map(Object.entries(govern).map(([resource, fields]) => [
+        resource,
+        Object.fromEntries(fields.map((field) => [
+            field,
+            (Object.hasOwn(modes, resource) &&
+                Object.hasOwn(modes[resource] ?? {}, field)
+                ? modes[resource]?.[field]
+                : undefined) ?? "both",
+        ])),
+    ]));
+};
+/** 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", governOf(a), governOf(b)),
+        ...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>;

package/dist/cli/pull.command.js

@@ -0,0 +1,234 @@
+// `avaccess pull [--namespace <namespace>] [--out <dir>]`: the namespace's current
+// policies file and the org's guardrails file, from the registry into the project,
+// and both hashes pinned in `avAccess.lock.json`. The only step that brings policies
+// over the network; commit what it writes. The namespace is `--namespace`, else the
+// lock's, else the one the key belongs to (the registry names it); the files go to `--out` (default: where the lock has them, else `access/`)
+// as `<namespace>.policies.json` and `guardrails.json`.
+//
+// A pull never lowers what the lock holds the project to: when the lock pins the
+// org's guardrails and the registry serves none, it is refused and nothing is
+// written. The file the registry serves is held to its hash and to the namespace
+// asked for (`registry.client.ts`). A signed revision, which would also prove who
+// wrote the file, is not built yet.
+//
+// Foreign facts: `--foreign <owner>:<Resource>[,<Resource>…]` (repeatable) brings the
+// owner's schema entries of those Resources into `foreign.json` beside the policies
+// file, marked as the owner's, so `avaccess schema` adds them to the rules' types;
+// a later pull keeps the ones pulled before. For every namespace the pulled file or
+// the foreign facts read, the pull reads that namespace's beacon through the
+// service's own connection (`--beacon <module>`, required then) and holds it to the
+// hash the namespace pushed: on another database it is refused
+// (`ACCESS_FOREIGN_CROSS_DATABASE`) and nothing is written. The lock pins the foreign
+// facts; each owner's beacon hash goes to the selected environment's
+// `avAccess.beacons.<environment>.json` (`--env`, else `AVACCESS_ENV`), which the
+// engine holds the owner's row to at startup (`checkBeacons`). The lock holds no
+// beacon, so it stays the same against any environment's registry.
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { BEACON_PINS_FORMAT, } from "../beacon/beacon.check.js";
+import { canonicalForeignFacts, FOREIGN_FILE, FOREIGN_FORMAT, foreignFactsHash, } from "../foreign/foreign-facts.js";
+import { canonicalGuardrails } from "../guardrails/guardrails.hash.js";
+import { LOCK_FILE, LOCK_FORMAT, } from "../lock/lock-contract.js";
+import { isName, isNamespace } from "../policies.compiler.js";
+import { canonicalPolicies } from "../policies.hash.js";
+import { foreignNamespaces } from "../registry/ownership.check.js";
+import { beaconStoreOf, holdOwnerBeacon } from "./beacon.loader.js";
+import { beaconPinsFile, ENV_VARIABLE, environmentOf, } from "./beacon-pins.file.js";
+import { CliFailure, EXIT_ERROR, EXIT_FAILED, EXIT_OK, positionals, stringFlag, } from "./cli.context.js";
+import { jsonText, readForeignPinned, readLockIfAny, writeProjectFile, } from "./lock.file.js";
+import { registryClient } from "./registry.client.js";
+/** Where pulled files go when neither `--out` nor the lock says. */
+const DEFAULT_OUT = "access";
+/** A directory relative to the project, `/`-separated, inside it. */
+const projectDirectory = (out) => {
+    const directory = out
+        .replace(/\\/g, "/")
+        .replace(/^\.\/+/, "")
+        .replace(/\/+$/, "");
+    if (directory === "" ||
+        directory.startsWith("/") ||
+        /^[A-Za-z]:/.test(directory) ||
+        directory.split("/").includes("..")) {
+        throw new CliFailure(EXIT_ERROR, `--out is a directory inside the project, such as "access"; it was ${JSON.stringify(out)}`);
+    }
+    return directory;
+};
+const directoryOf = (path) => path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : ".";
+/** The Resources `--foreign` names, by owner: `<owner>:<Resource>[,<Resource>…]`, each value. */
+const foreignFlags = (context) => {
+    const given = context.flags.foreign;
+    const values = given === undefined
+        ? []
+        : Array.isArray(given)
+            ? given
+            : [given];
+    const asked = new Map();
+    for (const value of values) {
+        const text = typeof value === "string" ? value : "";
+        const colon = text.indexOf(":");
+        const owner = text.slice(0, colon);
+        const resources = text.slice(colon + 1).split(",");
+        if (colon < 0 ||
+            !isNamespace(owner) ||
+            resources.some((resource) => !isName(resource))) {
+            throw new CliFailure(EXIT_ERROR, `--foreign names a namespace and the Resources the rules read of it, \`<namespace>:<Resource>[,<Resource>…]\` (such as \`campaign:Campaign,Member\`); it was ${JSON.stringify(text)}`);
+        }
+        const set = asked.get(owner) ?? new Set();
+        for (const resource of resources) {
+            set.add(resource);
+        }
+        asked.set(owner, set);
+    }
+    return asked;
+};
+/**
+ * The Resources the foreign facts the lock pins hold, by owner: none without a pin,
+ * and none when the file was deleted (how a project stops reading them). A file
+ * changed by hand is refused (`ACCESS_LOCK_MISMATCH`).
+ */
+const pulledForeign = async (context, lock, namespace) => {
+    const held = new Map();
+    if (lock?.foreign === undefined || lock.namespace !== namespace) {
+        return held;
+    }
+    try {
+        await access(resolve(context.cwd, lock.foreign.path));
+    }
+    catch {
+        return held;
+    }
+    const facts = await readForeignPinned(context.cwd, lock);
+    for (const [resource, entry] of Object.entries(facts?.schema ?? {})) {
+        const set = held.get(entry.foreign) ?? new Set();
+        set.add(resource);
+        held.set(entry.foreign, set);
+    }
+    return held;
+};
+export const pullCommand = async (context) => {
+    positionals(context, "avaccess pull [--namespace <namespace>] [--out <dir>] [--foreign <namespace>:<Resource>,…] [--beacon <module>] [--env <environment>]", 0, 0);
+    const lock = await readLockIfAny(context.cwd);
+    const registry = registryClient(context);
+    // With neither the flag nor a lock, the namespace is the key's own, as the
+    // registry names it: a first pull needs only the registry and the key.
+    const namespace = stringFlag(context, "namespace") ??
+        lock?.namespace ??
+        (await registry.keyNamespace());
+    if (!isNamespace(namespace)) {
+        throw new CliFailure(EXIT_ERROR, `${JSON.stringify(namespace)} is not a namespace name (a lowercase letter, then lowercase letters, digits, "_" or "-")`);
+    }
+    const flag = stringFlag(context, "out");
+    const out = flag !== undefined
+        ? projectDirectory(flag)
+        : lock !== undefined && lock.namespace === namespace
+            ? directoryOf(lock.policies.path)
+            : DEFAULT_OUT;
+    const prefix = out === "." ? "" : `${out}/`;
+    const head = await registry.head(namespace);
+    const guardrails = await registry.guardrails(namespace);
+    if (lock?.guardrails != null && guardrails === null) {
+        throw new CliFailure(EXIT_FAILED, `${LOCK_FILE} pins the org's guardrails (${lock.guardrails.path}, ${lock.guardrails.hash}), and the registry serves none: the pull would drop them, and the org's denies with them. Nothing was written. Check that ${registry.url} is the org's registry; if the org has removed its guardrails, delete ${LOCK_FILE} and pull again`);
+    }
+    // The foreign facts: those pulled before, and those `--foreign` asks for now.
+    const foreign = await pulledForeign(context, lock, namespace);
+    for (const [owner, resources] of foreignFlags(context)) {
+        if (owner === namespace) {
+            throw new CliFailure(EXIT_ERROR, `--foreign names namespace "${namespace}", this project's own: its Resources are read as its own`);
+        }
+        const set = foreign.get(owner) ?? new Set();
+        for (const resource of resources) {
+            set.add(resource);
+        }
+        foreign.set(owner, set);
+    }
+    const owners = [
+        ...new Set([...foreign.keys(), ...foreignNamespaces(head.file)]),
+    ].sort();
+    const entries = {};
+    const beacons = {};
+    const environment = environmentOf(context);
+    if (owners.length > 0) {
+        if (environment === undefined) {
+            throw new CliFailure(EXIT_ERROR, `namespace "${namespace}" reads ${owners.map((owner) => `"${owner}"`).join(", ")}'s Resources as foreign, whose beacons are pinned per environment: name it with \`--env <environment>\` or ${ENV_VARIABLE} (such as \`--env production\`). Nothing was written`);
+        }
+        const store = await beaconStoreOf(context);
+        if (store === undefined) {
+            throw new CliFailure(EXIT_ERROR, `namespace "${namespace}" reads ${owners.map((owner) => `"${owner}"`).join(", ")}'s Resources as foreign: pass the service's beacon store with \`--beacon <module>\`, so the pull can check that this service reaches ${owners.length === 1 ? "that namespace's" : "their"} database. Nothing was written`);
+        }
+        for (const owner of owners) {
+            const asked = [...(foreign.get(owner) ?? [])].sort();
+            const answer = await registry.foreign(namespace, owner, asked);
+            await holdOwnerBeacon(store, owner, answer.beacon);
+            beacons[owner] = answer.beacon;
+            for (const resource of asked) {
+                entries[resource] = {
+                    ...answer.resources[resource],
+                    foreign: owner,
+                };
+            }
+        }
+    }
+    const facts = Object.keys(entries).length === 0
+        ? undefined
+        : { format: FOREIGN_FORMAT, namespace, schema: entries };
+    let foreignHash;
+    if (facts !== undefined) {
+        try {
+            foreignHash = foreignFactsHash(facts);
+        }
+        catch (error) {
+            throw new CliFailure(EXIT_FAILED, `the registry's entries of ${Object.keys(entries).sort().join(", ")} make no foreign facts file (${error.message}). Nothing was written`);
+        }
+    }
+    const policiesPath = `${prefix}${namespace}.policies.json`;
+    const guardrailsPath = `${prefix}guardrails.json`;
+    const foreignPath = `${prefix}${FOREIGN_FILE}`;
+    await writeProjectFile(context.cwd, policiesPath, jsonText(JSON.parse(canonicalPolicies(head.file))));
+    if (guardrails !== null) {
+        await writeProjectFile(context.cwd, guardrailsPath, jsonText(JSON.parse(canonicalGuardrails(guardrails.file))));
+    }
+    if (facts !== undefined) {
+        await writeProjectFile(context.cwd, foreignPath, jsonText(JSON.parse(canonicalForeignFacts(facts))));
+    }
+    const next = {
+        format: LOCK_FORMAT,
+        namespace,
+        policies: { path: policiesPath, hash: head.hash },
+        guardrails: guardrails === null
+            ? null
+            : { path: guardrailsPath, hash: guardrails.hash },
+        ...(facts === undefined || foreignHash === undefined
+            ? {}
+            : { foreign: { path: foreignPath, hash: foreignHash } }),
+    };
+    await writeProjectFile(context.cwd, LOCK_FILE, jsonText(next));
+    if (environment !== undefined && owners.length > 0) {
+        const pins = {
+            format: BEACON_PINS_FORMAT,
+            namespace,
+            environment,
+            beacons,
+        };
+        await writeProjectFile(context.cwd, beaconPinsFile(environment), jsonText(pins));
+    }
+    context.out(`pulled namespace "${namespace}" at ${head.hash} into ${policiesPath}`);
+    context.out(guardrails === null
+        ? "the registry has no guardrails file for the org yet: none pinned"
+        : `pulled the org's guardrails at ${guardrails.hash} into ${guardrailsPath}`);
+    if (facts !== undefined) {
+        context.out(`pulled the foreign facts of ${Object.keys(entries)
+            .sort()
+            .map((resource) => `${resource} (namespace "${entries[resource]?.foreign}")`)
+            .join(", ")} into ${foreignPath}`);
+    }
+    if (owners.length > 0) {
+        context.out(`checked the beacon${owners.length === 1 ? "" : "s"} of ${owners.map((owner) => `"${owner}"`).join(", ")}: this service reaches ${owners.length === 1 ? "its" : "their"} database; pinned for environment "${environment}" in ${beaconPinsFile(environment)}`);
+    }
+    context.out(`wrote ${LOCK_FILE}${lock === undefined
+        ? ""
+        : lock.policies.hash === head.hash &&
+            (lock.guardrails?.hash ?? null) === (guardrails?.hash ?? null)
+            ? " (unchanged)"
+            : " (updated)"}: commit it with the pulled files`);
+    return EXIT_OK;
+};

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

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

package/dist/cli/push.command.js

@@ -0,0 +1,59 @@
+// `avaccess push <rules>`: the namespace's policies file, to the registry, with the
+// namespace's push key. `<rules>` is the compiled file (`.json`) or the module that
+// holds the rules (`definePolicies(model, { namespace })…`, or its `.contract()`), as
+// its default export or as `rules`. The namespace is the file's own. The registry
+// checks ownership and stores the file as an immutable revision under its hash.
+//
+// With `--beacon <module>` (the service's beacon store, `beacon.loader.ts`) the push
+// carries the namespace's own beacon, its row in `_aventara_beacon` written the first
+// time, and the beacon of each namespace the file reads as foreign, as the service's
+// connection reads it: the registry keeps the first as the namespace's, and stores a
+// file that reads another namespace only when the second matches what that
+// namespace pushed (`ACCESS_FOREIGN_CROSS_DATABASE`).
+import { isRecord } from "../policies.compiler.js";
+import { POLICIES_FORMAT } from "../policies-contract.js";
+import { foreignNamespaces } from "../registry/ownership.check.js";
+import { beaconStoreOf, ownBeacon, readOwnerBeacon } from "./beacon.loader.js";
+import { CliFailure, codeOf, EXIT_ERROR, EXIT_FAILED, EXIT_OK, messageOf, positionals, } from "./cli.context.js";
+import { loadProjectModule, pickExport } from "./module.loader.js";
+import { registryClient } from "./registry.client.js";
+const isRules = (value) => isRecord(value) &&
+    (typeof value.contract === "function" || value.format === POLICIES_FORMAT);
+export const pushCommand = async (context) => {
+    const [path] = positionals(context, "avaccess push <rules> [--beacon <module>]", 1, 1);
+    const exports = await loadProjectModule(context.cwd, path);
+    const rules = pickExport(exports, path, "rules", isRules, "policies file or `definePolicies(…)` rules");
+    let file;
+    try {
+        file = "contract" in rules ? rules.contract() : rules;
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_FAILED, messageOf(error), codeOf(error));
+    }
+    const namespace = file.namespace;
+    if (typeof namespace !== "string") {
+        throw new CliFailure(EXIT_ERROR, `the rules in ${path} name no namespace: a pushed file belongs to one, \`definePolicies(model, { namespace: "<namespace>" })\``);
+    }
+    const store = await beaconStoreOf(context);
+    const owners = foreignNamespaces(file);
+    const registry = registryClient(context);
+    let beacons;
+    if (store !== undefined) {
+        beacons = {
+            [namespace]: await ownBeacon(store, namespace, await registry.namespaceBeacon(namespace)),
+        };
+        for (const owner of owners) {
+            beacons[owner] = await readOwnerBeacon(store, owner);
+        }
+    }
+    const pushed = await registry.push(namespace, file, beacons);
+    if (beacons !== undefined) {
+        context.out(`sent namespace "${namespace}"'s beacon${owners.length === 0
+            ? ""
+            : `, and the beacon${owners.length === 1 ? "" : "s"} of ${owners.map((owner) => `"${owner}"`).join(", ")} as this service's connection reads ${owners.length === 1 ? "it" : "them"}`}`);
+    }
+    context.out(pushed.created
+        ? `pushed namespace "${namespace}": ${pushed.hash}, a new revision, now its head`
+        : `pushed namespace "${namespace}": ${pushed.hash}, which the registry had; it is its head again`);
+    return EXIT_OK;
+};

package/dist/cli/registry.client.d.ts

@@ -0,0 +1,63 @@
+import type { AccessGuardrails } from "../guardrails/guardrails-contract.js";
+import type { AccessPolicies, AccessSchemaResourceFacts } from "../policies-contract.js";
+import { type CliContext } from "./cli.context.js";
+/** The environment variable that holds the registry's URL, when `--registry` does not. */
+export declare const REGISTRY_URL_VARIABLE = "AVACCESS_REGISTRY_URL";
+/** The environment variable that holds the namespace's key. */
+export declare const KEY_VARIABLE = "AVACCESS_KEY";
+/** A revision as the registry answers it, its file hashed again. */
+type PulledRevision<File> = {
+    readonly hash: string;
+    readonly file: File;
+};
+/** What a namespace reads of another one as foreign, as the registry answers it. */
+type ForeignAnswer = {
+    /** The hash of the beacon the owner pushed; `null` when it has pushed none. */
+    readonly beacon: string | null;
+    /** The owner's schema entry of each Resource asked for. */
+    readonly resources: {
+        readonly [resource: string]: AccessSchemaResourceFacts;
+    };
+};
+/** One revision in a namespace's list, newest first. */
+type RevisionEntry = {
+    readonly hash: string;
+    readonly createdAt: string;
+};
+/** The registry the context names, with its key. */
+export declare const registryClient: (context: CliContext) => {
+    url: string;
+    /** The namespace the key belongs to, as the registry names it. */
+    keyNamespace: () => Promise<string>;
+    /** The hash of the namespace's current beacon (`null`: it has pushed none). */
+    namespaceBeacon: (namespace: string) => Promise<string | null>;
+    /** The namespace's current revision's hash (`null`: nothing pushed yet). */
+    headHash: (namespace: string) => Promise<string | null>;
+    /** The namespace's current revision, with its file. */
+    head: (namespace: string) => Promise<PulledRevision<AccessPolicies>>;
+    /** One of the namespace's revisions, with its file. */
+    revision: (namespace: string, hash: string) => Promise<PulledRevision<AccessPolicies>>;
+    /** The namespace's revisions, newest first. */
+    revisions: (namespace: string) => Promise<readonly RevisionEntry[]>;
+    /** The org's current guardrails, with their file (`null`: none pushed yet). */
+    guardrails: (namespace: string) => Promise<PulledRevision<AccessGuardrails> | null>;
+    /**
+     * 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: (namespace: string, owner: string, resources: readonly string[]) => Promise<ForeignAnswer>;
+    /**
+     * 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: (namespace: string, file: unknown, beacons?: {
+        readonly [namespace: string]: string;
+    }) => Promise<{
+        readonly hash: string;
+        readonly created: boolean;
+    }>;
+};
+/** The registry client `registryClient` builds. */
+export type RegistryClient = ReturnType<typeof registryClient>;
+export {};