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

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

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