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

package/dist/registry/access.registry.js

@@ -0,0 +1,865 @@
+// The policy registry: namespaces, their keys, the pushed files and the org's
+// guardrails, kept in the registry's tables (`registry.schema.ts`) through Better
+// Auth's database adapter. One org per server: the namespaces and the guardrails
+// file are the server's own.
+//
+// - A revision is a file in its canonical text under its hash (`policiesHash`, and
+//   for the org's guardrails file, `guardrailsHash`). It
+//   is written once and never updated: a push of a file the registry has already
+//   writes no revision, it only moves the head back to it. A revision read back is
+//   hashed again, and one that no longer matches its hash is never served.
+// - A namespace's head is its current revision; the org's guardrails have one too.
+//   A push checks ownership against the owners table, claims the Resources it names
+//   as its own, writes the revision, moves the head and logs the push in one
+//   transaction; the owners table's unique Resource name refuses a second claim
+//   made at the same time.
+// - Keys are stored as hashes (`registry.key.ts`), one live key per namespace and
+//   kind. A refusal never quotes the key, and answers a key of another namespace as
+//   it answers a namespace that does not exist.
+//
+// The operator's half (namespaces, keys, the guardrails file) is a programmatic API
+// on the instance, `access.registry`; the services' half (push, and the read-only
+// reads a pull makes) is served over HTTP by `registry.endpoints.ts`.
+import { AccessError } from "../access/access.error.js";
+import { checkGuardrails } from "../guardrails/guardrails.compiler.js";
+import { canonicalGuardrails } from "../guardrails/guardrails.hash.js";
+import { checkPolicies, isName, isNamespace } from "../policies.compiler.js";
+import { canonicalPolicies } from "../policies.hash.js";
+import { sha256Hex } from "../sha256.digest.js";
+import { beaconRolledBack, checkPushedBeacons, pushedOf, storedBeaconHash, } from "./beacon.ledger.js";
+import { checkForeignMarkers, checkGuardrailNamespaces, checkGuardrailsOwnership, checkNamespaceOwnership, foreignNamespaces, ownResources, resourcesNamed, } from "./ownership.check.js";
+import { KEY_KINDS, keyHashOf, newKey, } from "./registry.key.js";
+import { AccessRegistryRefusal } from "./registry.refusal.js";
+import { REGISTRY_MODELS } from "./registry.schema.js";
+export { AccessRegistryRefusal } from "./registry.refusal.js";
+/**
+ * The most rows one list reads. A list that would be longer is refused, naming
+ * what is too long: never cut short.
+ */
+const MANY = 10_000;
+/** A revision's hash, as a route names it. */
+const HASH = /^sha256:[0-9a-f]{64}$/;
+/** The largest policies file a push stores, in bytes of its JSON text: 1 MiB. */
+export const MAX_POLICIES_BYTES = 1_048_576;
+/** How long the push log adds refusals of no key of this registry into one row. */
+const REFUSALS_WINDOW_MS = 60_000;
+/** How long a refusal of no key of this registry waits, counted in memory, before its row's count is written. */
+const REFUSALS_FLUSH_MS = 1_000;
+/** How often `revokeKey` and `assignResource` run again when another call at the same time took a unique slot first (`rotateKey` runs once: see there). */
+const KEY_ATTEMPTS = 3;
+/** The most Resources one foreign read names. */
+const MAX_FOREIGN_RESOURCES = 100;
+const NOT_A_KEY = 401;
+const NOT_ALLOWED = 403;
+const namespaceLine = (namespace) => `namespace:${namespace}`;
+const GUARDRAILS_LINE = "guardrails";
+const by = (field, value) => [{ field, value }];
+const among = (field, values) => [
+    { field, operator: "in", value: [...values] },
+];
+const unique = (values) => {
+    const seen = new Set();
+    const kept = [];
+    for (const value of values) {
+        if (!seen.has(value)) {
+            seen.add(value);
+            kept.push(value);
+        }
+    }
+    return kept;
+};
+/** The bytes of a pushed body's JSON text; `undefined` when it has none (too deep, a cycle). */
+const bytesOf = (body) => {
+    try {
+        const text = JSON.stringify(body);
+        return text === undefined ? 0 : new TextEncoder().encode(text).length;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Runs `run` again when it failed on something other than a refusal: another call at
+ * the same time took a unique slot first, and the next attempt sees what it wrote.
+ * Past `KEY_ATTEMPTS` tries it throws `exhausted`'s refusal, naming the call and the
+ * last failure, never the database's error alone.
+ */
+const retried = async (run, exhausted) => {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            if (error instanceof AccessError) {
+                throw error;
+            }
+            if (attempt >= KEY_ATTEMPTS) {
+                throw exhausted(error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+};
+/** A key call that failed `KEY_ATTEMPTS` times. */
+const keyCallFailed = (call) => (last) => new AccessError("ACCESS_KEY_REFUSED", `${call} failed ${KEY_ATTEMPTS} times: other key calls on the same namespace at the same time, or the database refused the write (last: ${last}). Run it again`);
+/** A pushed file, checked as the engine would check it, in its canonical text and hash. */
+const canonical = (file, check, text) => {
+    try {
+        check(file);
+    }
+    catch (error) {
+        throw new AccessError("ACCESS_POLICIES_INVALID", String(error.message).replace(/^Aventara Access: /, ""));
+    }
+    const written = text(file);
+    return {
+        format: file.format,
+        text: written,
+        hash: `sha256:${sha256Hex(written)}`,
+    };
+};
+/** A stored revision, after checking it still hashes to the hash it is stored under. */
+const served = (row) => {
+    if (`sha256:${sha256Hex(row.file)}` !== row.hash) {
+        throw new AccessRegistryRefusal("ACCESS_REVISION_CHANGED", `the stored revision ${row.hash} was changed outside the registry: its text no longer hashes to its hash, and the registry never updates a revision. Push the file again from its source`, 500);
+    }
+    return {
+        hash: row.hash,
+        format: row.format,
+        createdAt: row.createdAt,
+        file: JSON.parse(row.file),
+    };
+};
+/** The registry over the adapter `adapterOf` resolves (Better Auth's, once it is built). */
+export const createRegistry = (adapterOf, settings = { ownership: "first-push" }) => {
+    /** Up to `MANY` rows of a list; a longer one is refused with `tooMany`, never cut short. */
+    const atMost = async (adapter, input, tooMany) => {
+        const rows = await adapter.findMany({ ...input, limit: MANY + 1 });
+        if (rows.length > MANY) {
+            throw new AccessRegistryRefusal("ACCESS_NAMESPACE", tooMany, 500);
+        }
+        return rows;
+    };
+    const namespaceNamed = async (adapter, name) => {
+        const row = isNamespace(name)
+            ? await adapter.findOne({
+                model: REGISTRY_MODELS.namespace,
+                where: by("name", name),
+            })
+            : null;
+        if (row === null) {
+            throw new AccessError("ACCESS_NAMESPACE", `the registry has no namespace ${JSON.stringify(name)}; createNamespace adds one`);
+        }
+        return row;
+    };
+    /** The namespaces among `names` the registry has. */
+    const namespacesAmong = async (adapter, names) => {
+        const wanted = unique(names.filter(isNamespace));
+        if (wanted.length === 0) {
+            return new Set();
+        }
+        const rows = await adapter.findMany({
+            model: REGISTRY_MODELS.namespace,
+            where: among("name", wanted),
+            limit: wanted.length,
+        });
+        return new Set(rows.map((row) => row.name));
+    };
+    const checkKind = (kind) => {
+        if (!KEY_KINDS.includes(kind)) {
+            throw new AccessError("ACCESS_OPTIONS_INVALID", `a key's kind is "push" or "pull"; it was ${JSON.stringify(kind)}`);
+        }
+        return kind;
+    };
+    /** The one slot a namespace's live key of `kind` holds. */
+    const slotOf = (namespaceId, kind) => `${namespaceId}:${kind}`;
+    const revoke = async (adapter, namespaceId, kind) => {
+        const live = await adapter.findOne({
+            model: REGISTRY_MODELS.key,
+            where: by("slot", slotOf(namespaceId, kind)),
+        });
+        if (live !== null) {
+            await adapter.update({
+                model: REGISTRY_MODELS.key,
+                where: by("id", live.id),
+                update: { revokedAt: new Date(), slot: null },
+            });
+        }
+    };
+    const issue = async (adapter, namespaceId, kind) => {
+        const key = newKey(kind);
+        await adapter.create({
+            model: REGISTRY_MODELS.key,
+            data: {
+                namespaceId,
+                kind,
+                keyHash: keyHashOf(key),
+                slot: slotOf(namespaceId, kind),
+            },
+        });
+        return key;
+    };
+    /** The key row `key` names, or `null` for text that is no key of this registry. */
+    const keyRowOf = async (adapter, key) => {
+        const hash = keyHashOf(key ?? "");
+        return hash === undefined
+            ? null
+            : adapter.findOne({
+                model: REGISTRY_MODELS.key,
+                where: by("keyHash", hash),
+            });
+    };
+    /** The key and the namespace a request names, as far as the registry has them. */
+    const lookUp = async (adapter, namespace, key) => ({
+        key: await keyRowOf(adapter, key),
+        namespace: isNamespace(namespace)
+            ? await adapter.findOne({
+                model: REGISTRY_MODELS.namespace,
+                where: by("name", namespace),
+            })
+            : null,
+    });
+    /**
+     * The namespace a key opens for `kinds`, or a refusal that names what is wrong
+     * with the key and never the key itself. A key of another namespace is answered
+     * as a namespace the registry does not have: neither tells the caller which
+     * namespaces exist.
+     */
+    const opens = (namespace, key, found, kinds) => {
+        const { key: row, namespace: owner } = found;
+        if (row === null || owner === null || row.namespaceId !== owner.id) {
+            throw new AccessRegistryRefusal("ACCESS_KEY_REFUSED", key === undefined || key === ""
+                ? "the request carries no registry key: send the namespace's key in the x-access-key header"
+                : `the x-access-key header holds no key of namespace ${JSON.stringify(namespace)} in this registry`, NOT_A_KEY);
+        }
+        if (row.revokedAt != null) {
+            throw new AccessRegistryRefusal("ACCESS_KEY_REFUSED", `the ${row.kind} key in the x-access-key header was revoked or rotated out; ask the operator for the namespace's current one`, NOT_A_KEY);
+        }
+        if (!kinds.includes(row.kind)) {
+            throw new AccessRegistryRefusal("ACCESS_KEY_REFUSED", `a ${row.kind} key only reads; a push takes namespace "${namespace}"'s push key`, NOT_ALLOWED);
+        }
+        return { namespace: owner, key: row };
+    };
+    const authorize = async (adapter, namespace, key, kinds) => opens(namespace, key, await lookUp(adapter, namespace, key), kinds);
+    /** The owner rows of `resources`, and who owns each by namespace name. */
+    const ownersOf = async (adapter, resources) => {
+        const wanted = unique(resources);
+        if (wanted.length === 0) {
+            return { rows: [], owners: new Map() };
+        }
+        const rows = await adapter.findMany({
+            model: REGISTRY_MODELS.owner,
+            where: among("resource", wanted),
+            limit: wanted.length,
+        });
+        const ids = unique(rows.map((row) => row.namespaceId));
+        const namespaces = ids.length === 0
+            ? []
+            : await adapter.findMany({
+                model: REGISTRY_MODELS.namespace,
+                where: among("id", ids),
+                limit: ids.length,
+            });
+        const names = new Map();
+        for (const row of namespaces) {
+            names.set(row.id, row.name);
+        }
+        const owners = new Map();
+        for (const row of rows) {
+            owners.set(row.resource, names.get(row.namespaceId) ?? "");
+        }
+        return { rows, owners };
+    };
+    /**
+     * Checks ownership of a file pushed to `namespace` against what `adapter` reads
+     * now, but for its foreign markers (`checkMarkers`), and answers what it read:
+     * the owner rows, and who owns each Resource the file names.
+     */
+    const checkOwnership = async (adapter, namespace, pushed) => {
+        const read = await ownersOf(adapter, resourcesNamed(pushed.file));
+        checkNamespaceOwnership(namespace, pushed.file, read.owners, settings.ownership);
+        return read;
+    };
+    /**
+     * Checks a push's beacons, then its file's foreign markers. In that order: a
+     * service that cannot show it shares a marked namespace's database gets the one
+     * beacon refusal, whatever that namespace is or owns, so it learns nothing of who
+     * owns what.
+     */
+    const checkMarkers = async (adapter, namespace, pushed, owners) => {
+        const marked = foreignNamespaces(pushed.file);
+        checkPushedBeacons(namespace, marked, pushed.beacons, await beaconsOf(adapter, marked));
+        checkForeignMarkers(namespace, pushed.file, owners, await namespacesAmong(adapter, marked));
+    };
+    /**
+     * With first-push ownership: claims the Resources `file` names as its own that no
+     * namespace owns yet, and gives back those this namespace claimed by a push and
+     * its new file no longer names. A claim another push made at the same time fails
+     * the owners table's unique Resource name, and with it the transaction.
+     */
+    const claim = async (adapter, namespaceId, file, known) => {
+        const own = new Set(ownResources(file));
+        const owned = new Set(known.map((row) => row.resource));
+        for (const resource of own) {
+            if (!owned.has(resource)) {
+                await adapter.create({
+                    model: REGISTRY_MODELS.owner,
+                    data: { resource, namespaceId, source: "push" },
+                });
+            }
+        }
+        const held = await atMost(adapter, {
+            model: REGISTRY_MODELS.owner,
+            where: [...by("namespaceId", namespaceId), ...by("source", "push")],
+        }, `a namespace holds more than ${MANY} Resources claimed by its pushes, more than the registry reads in one list`);
+        for (const row of held) {
+            if (!own.has(row.resource)) {
+                await adapter.delete({
+                    model: REGISTRY_MODELS.owner,
+                    where: by("id", row.id),
+                });
+            }
+        }
+    };
+    const setHead = async (adapter, line, hash) => {
+        const current = await adapter.findOne({
+            model: REGISTRY_MODELS.head,
+            where: by("line", line),
+        });
+        if (current === null) {
+            await adapter.create({
+                model: REGISTRY_MODELS.head,
+                data: { line, hash, updatedAt: new Date() },
+            });
+        }
+        else if (current.hash !== hash) {
+            await adapter.update({
+                model: REGISTRY_MODELS.head,
+                where: by("id", current.id),
+                update: { hash, updatedAt: new Date() },
+            });
+        }
+    };
+    const log = (adapter, entry) => adapter.create({
+        model: REGISTRY_MODELS.pushLog,
+        data: {
+            line: entry.line,
+            keyId: entry.keyId ?? null,
+            hash: entry.hash ?? null,
+            outcome: entry.outcome,
+            code: entry.code ?? null,
+            count: 1,
+        },
+    });
+    const unkeyed = new Map();
+    /** Writes an open row's count once `REFUSALS_FLUSH_MS` has passed; a failed write is dropped (the row is a log). */
+    const flushLater = (adapter, open) => {
+        if (open.flush !== undefined) {
+            return;
+        }
+        open.flush = setTimeout(() => {
+            open.flush = undefined;
+            open.id
+                .then((id) => adapter.update({
+                model: REGISTRY_MODELS.pushLog,
+                where: by("id", id),
+                update: { count: open.count },
+            }))
+                .catch(() => undefined);
+        }, REFUSALS_FLUSH_MS);
+        open.flush.unref?.();
+    };
+    const countUnkeyed = async (adapter, line) => {
+        const now = Date.now();
+        const open = unkeyed.get(line);
+        if (open !== undefined && now < open.until) {
+            open.count += 1;
+            flushLater(adapter, open);
+            return;
+        }
+        const id = log(adapter, {
+            line,
+            outcome: "refused",
+            code: "ACCESS_KEY_REFUSED",
+        }).then((row) => row.id);
+        unkeyed.set(line, {
+            id,
+            until: now + REFUSALS_WINDOW_MS,
+            count: 1,
+            flush: undefined,
+        });
+        await id;
+    };
+    /** Stores a checked file as a revision of `model` (unless it is there), moves `line`'s head to it and logs the push. */
+    const store = async (adapter, model, line, file, extra, keyId) => {
+        const existing = await adapter.findOne({
+            model,
+            where: by("hash", file.hash),
+        });
+        if (existing === null) {
+            await adapter.create({
+                model,
+                data: {
+                    ...extra,
+                    hash: file.hash,
+                    format: file.format,
+                    file: file.text,
+                },
+            });
+        }
+        await setHead(adapter, line, file.hash);
+        await log(adapter, { line, keyId, hash: file.hash, outcome: "accepted" });
+        return { hash: file.hash, created: existing === null };
+    };
+    /** A namespace a key opens, then what `read` answers for it. */
+    const keyed = (read) => async (namespace, key, ...args) => {
+        const adapter = await adapterOf();
+        const opened = await authorize(adapter, namespace, key, ["pull", "push"]);
+        return read(adapter, opened.namespace, ...args);
+    };
+    /** The revision of `model` stored under `hash` (of the namespace `namespaceId`, for a policies revision). */
+    const revisionOf = async (adapter, model, hash, namespaceId) => {
+        const row = await adapter.findOne({
+            model,
+            where: [
+                ...by("hash", hash),
+                ...(namespaceId === undefined ? [] : by("namespaceId", namespaceId)),
+            ],
+        });
+        return row === null ? null : served(row);
+    };
+    const headOf = async (adapter, line) => (await adapter.findOne({
+        model: REGISTRY_MODELS.head,
+        where: by("line", line),
+    }))?.hash ?? null;
+    const checkResource = (resource) => {
+        if (!isName(resource)) {
+            throw new AccessError("ACCESS_OWNERSHIP", `${JSON.stringify(resource)} is not a Resource name (a letter or "_", then letters, digits or "_")`);
+        }
+        return resource;
+    };
+    /** The current beacon hash of each of `names` (`null`: none, or no such namespace). */
+    const beaconsOf = async (adapter, names) => {
+        const found = new Map();
+        for (const name of names) {
+            found.set(name, null);
+        }
+        const wanted = unique(names.filter(isNamespace));
+        if (wanted.length === 0) {
+            return found;
+        }
+        const namespaces = await adapter.findMany({
+            model: REGISTRY_MODELS.namespace,
+            where: among("name", wanted),
+            limit: wanted.length,
+        });
+        const rows = namespaces.length === 0
+            ? []
+            : await adapter.findMany({
+                model: REGISTRY_MODELS.beacon,
+                where: among("slot", namespaces.map((row) => row.id)),
+                limit: namespaces.length,
+            });
+        for (const row of namespaces) {
+            found.set(row.name, rows.find((beacon) => beacon.slot === row.id)?.beaconHash ?? null);
+        }
+        return found;
+    };
+    /**
+     * Keeps the pushing namespace's own beacon when the push carries one (the push
+     * checked its beacons against what the registry keeps first): only a
+     * namespace's own push registers or replaces its beacon, and a reader only
+     * refers to an owner's. A new one is added; a changed one retires the current
+     * one and takes its slot; one the namespace pushed before and replaced is a
+     * rollback, refused.
+     */
+    const settleBeacons = async (adapter, namespace, beacons) => {
+        const own = beacons[namespace.name];
+        if (own === undefined) {
+            return;
+        }
+        const beaconHash = storedBeaconHash(namespace.name, own);
+        const seen = await adapter.findOne({
+            model: REGISTRY_MODELS.beacon,
+            where: by("beaconHash", beaconHash),
+        });
+        if (seen !== null) {
+            // Bound to the namespace, a hash is only ever this namespace's.
+            if (seen.slot === namespace.id) {
+                return;
+            }
+            beaconRolledBack(namespace.name);
+        }
+        const current = await adapter.findOne({
+            model: REGISTRY_MODELS.beacon,
+            where: by("slot", namespace.id),
+        });
+        if (current !== null) {
+            await adapter.update({
+                model: REGISTRY_MODELS.beacon,
+                where: by("id", current.id),
+                update: { slot: null, retiredAt: new Date() },
+            });
+        }
+        await adapter.create({
+            model: REGISTRY_MODELS.beacon,
+            data: { namespaceId: namespace.id, beaconHash, slot: namespace.id },
+        });
+    };
+    /** The one refusal of a foreign read that is not the namespace's to make. */
+    const notRead = (namespace) => {
+        throw new AccessRegistryRefusal("ACCESS_OWNERSHIP", `namespace "${namespace}"'s current file does not read that as foreign: push a file whose schema marks each Resource it reads { "foreign": "<its owner>" } first, then pull its owner's facts`, 404);
+    };
+    /** A foreign read, its request held to the namespace's current file (see `foreign`). */
+    const foreignRead = async (adapter, row, owner, names) => {
+        if (names.length > MAX_FOREIGN_RESOURCES ||
+            !isNamespace(owner) ||
+            owner === row.name) {
+            return notRead(row.name);
+        }
+        const ownHash = await headOf(adapter, namespaceLine(row.name));
+        const own = ownHash === null
+            ? null
+            : await revisionOf(adapter, REGISTRY_MODELS.policyRevision, ownHash, row.id);
+        const read = new Set(Object.entries(own?.file.schema ?? {})
+            .filter(([, facts]) => facts.foreign === owner)
+            .map(([resource]) => resource));
+        if (read.size === 0 || names.some((resource) => !read.has(resource))) {
+            return notRead(row.name);
+        }
+        const ownerRow = await adapter.findOne({
+            model: REGISTRY_MODELS.namespace,
+            where: by("name", owner),
+        });
+        if (ownerRow === null) {
+            return notRead(row.name);
+        }
+        const facts = {};
+        if (names.length > 0) {
+            const { owners } = await ownersOf(adapter, names);
+            const ownerHash = await headOf(adapter, namespaceLine(owner));
+            const head = ownerHash === null
+                ? null
+                : await revisionOf(adapter, REGISTRY_MODELS.policyRevision, ownerHash, ownerRow.id);
+            for (const resource of names) {
+                const entry = head?.file.schema[resource];
+                if (owners.get(resource) !== owner ||
+                    entry === undefined ||
+                    entry.foreign !== undefined) {
+                    return notRead(row.name);
+                }
+                facts[resource] = entry;
+            }
+        }
+        return {
+            owner,
+            beacon: (await beaconsOf(adapter, [owner])).get(owner) ?? null,
+            resources: facts,
+        };
+    };
+    /**
+     * The namespace and key a push opens, or its refusal. A refusal of a key the
+     * registry has is logged with that key. One of no key of this registry is only
+     * counted, and only for a namespace it has: no caller without a key writes a row
+     * of its own.
+     */
+    const admitted = async (adapter, namespace, key) => {
+        const found = await lookUp(adapter, namespace, key);
+        try {
+            return opens(namespace, key, found, ["push"]);
+        }
+        catch (error) {
+            if (error instanceof AccessError) {
+                const line = namespaceLine(namespace);
+                if (found.key !== null) {
+                    await log(adapter, {
+                        line,
+                        keyId: found.key.id,
+                        outcome: "refused",
+                        code: error.code,
+                    });
+                }
+                else if (found.namespace !== null) {
+                    await countUnkeyed(adapter, line);
+                }
+            }
+            throw error;
+        }
+    };
+    const operator = {
+        createNamespace: async (name) => {
+            if (!isNamespace(name)) {
+                throw new AccessError("ACCESS_NAMESPACE", `${JSON.stringify(name)} is not a namespace name (a lowercase letter, then lowercase letters, digits, "_" or "-"; at most 63 characters)`);
+            }
+            const adapter = await adapterOf();
+            return adapter.transaction(async (trx) => {
+                const existing = await trx.findOne({
+                    model: REGISTRY_MODELS.namespace,
+                    where: by("name", name),
+                });
+                if (existing !== null) {
+                    throw new AccessError("ACCESS_NAMESPACE", `the registry has namespace "${name}" already; rotateKey issues it new keys`);
+                }
+                const row = await trx.create({
+                    model: REGISTRY_MODELS.namespace,
+                    data: { name },
+                });
+                return {
+                    namespace: name,
+                    push: await issue(trx, row.id, "push"),
+                    pull: await issue(trx, row.id, "pull"),
+                };
+            });
+        },
+        rotateKey: async (namespace, kind) => {
+            const checked = checkKind(kind);
+            const adapter = await adapterOf();
+            const call = `rotateKey(${JSON.stringify(namespace)}, "${checked}")`;
+            const overtaken = () => {
+                throw new AccessError("ACCESS_KEY_REFUSED", `another rotateKey or revokeKey of namespace ${JSON.stringify(namespace)}'s ${checked} key ran at the same time as this ${call}, so the key it would issue is not the live one and is not shown: the other call's answer stands. Run rotateKey again for a new key`);
+            };
+            const slotHolder = async () => {
+                const row = await namespaceNamed(adapter, namespace);
+                return ((await adapter.findOne({
+                    model: REGISTRY_MODELS.key,
+                    where: by("slot", slotOf(row.id, checked)),
+                }))?.id ?? null);
+            };
+            // One try: a rotation that lost the key's slot to another one at the same time
+            // is refused rather than run again, since running it again would revoke the key
+            // the other call has just handed back.
+            const before = await slotHolder();
+            let key;
+            try {
+                key = await adapter.transaction(async (trx) => {
+                    const row = await namespaceNamed(trx, namespace);
+                    await revoke(trx, row.id, checked);
+                    return issue(trx, row.id, checked);
+                });
+            }
+            catch (error) {
+                if (error instanceof AccessError) {
+                    throw error;
+                }
+                const after = await slotHolder().catch(() => before);
+                if (after !== null && after !== before) {
+                    overtaken();
+                }
+                throw new AccessError("ACCESS_KEY_REFUSED", `${call} did not take the key's slot: the database refused the write (${error instanceof Error ? error.message : String(error)}). Run it again`);
+            }
+            // Another call that committed after this one replaced the key it issued:
+            // handing it back would show the operator a key that no longer opens anything.
+            const issued = await keyRowOf(adapter, key);
+            if (issued === null || issued.revokedAt != null) {
+                overtaken();
+            }
+            return key;
+        },
+        revokeKey: async (namespace, kind) => {
+            const checked = checkKind(kind);
+            const adapter = await adapterOf();
+            await retried(() => adapter.transaction(async (trx) => revoke(trx, (await namespaceNamed(trx, namespace)).id, checked)), keyCallFailed(`revokeKey(${JSON.stringify(namespace)}, "${checked}")`));
+        },
+        pushGuardrails: async (file) => {
+            const adapter = await adapterOf();
+            try {
+                checkGuardrailsOwnership(file);
+                const checked = canonical(file, checkGuardrails, canonicalGuardrails);
+                checkGuardrailNamespaces(file, await namespacesAmong(adapter, file.denies.flatMap((guardrail) => guardrail.resources === "*"
+                    ? []
+                    : Object.keys(guardrail.resources))));
+                return await adapter.transaction((trx) => store(trx, REGISTRY_MODELS.guardrailRevision, GUARDRAILS_LINE, checked, {}, undefined));
+            }
+            catch (error) {
+                if (error instanceof AccessError) {
+                    await log(adapter, {
+                        line: GUARDRAILS_LINE,
+                        outcome: "refused",
+                        code: error.code,
+                    });
+                }
+                throw error;
+            }
+        },
+        assignResource: async (resource, namespace) => {
+            const checked = checkResource(resource);
+            const adapter = await adapterOf();
+            await retried(() => adapter.transaction(async (trx) => {
+                const row = await namespaceNamed(trx, namespace);
+                const current = await trx.findOne({
+                    model: REGISTRY_MODELS.owner,
+                    where: by("resource", checked),
+                });
+                if (current === null) {
+                    await trx.create({
+                        model: REGISTRY_MODELS.owner,
+                        data: {
+                            resource: checked,
+                            namespaceId: row.id,
+                            source: "operator",
+                        },
+                    });
+                }
+                else if (current.namespaceId !== row.id ||
+                    current.source !== "operator") {
+                    await trx.update({
+                        model: REGISTRY_MODELS.owner,
+                        where: by("id", current.id),
+                        update: { namespaceId: row.id, source: "operator" },
+                    });
+                }
+            }), (last) => new AccessError("ACCESS_OWNERSHIP", `assignResource(${JSON.stringify(checked)}, ${JSON.stringify(namespace)}) did not take the Resource in ${KEY_ATTEMPTS} tries: other calls on it at the same time took it each time, or the database refused the write (last: ${last}). Run it again`));
+        },
+        releaseResource: async (resource) => {
+            const checked = checkResource(resource);
+            const adapter = await adapterOf();
+            await adapter.delete({
+                model: REGISTRY_MODELS.owner,
+                where: by("resource", checked),
+            });
+        },
+    };
+    return {
+        operator,
+        /**
+         * The namespace a key belongs to, and its kind: what `avaccess pull` reads when
+         * the project has no lock yet. A key that is not one of this registry's, or was
+         * revoked, is refused as a read with it would be.
+         */
+        keyOwner: async (key) => {
+            const adapter = await adapterOf();
+            const row = await keyRowOf(adapter, key);
+            const owner = row === null
+                ? null
+                : await adapter.findOne({
+                    model: REGISTRY_MODELS.namespace,
+                    where: by("id", row.namespaceId),
+                });
+            if (row === null || owner === null) {
+                throw new AccessRegistryRefusal("ACCESS_KEY_REFUSED", key === undefined || key === ""
+                    ? "the request carries no registry key: send the namespace's key in the x-access-key header"
+                    : "the x-access-key header holds no key of this registry", NOT_A_KEY);
+            }
+            if (row.revokedAt != null) {
+                throw new AccessRegistryRefusal("ACCESS_KEY_REFUSED", `the ${row.kind} key in the x-access-key header was revoked or rotated out; ask the operator for the namespace's current one`, NOT_A_KEY);
+            }
+            return { namespace: owner.name, kind: row.kind };
+        },
+        /**
+         * Whether `key` is `namespace`'s push key: the refusal a push would get
+         * (`ACCESS_KEY_REFUSED`, logged as a push's), or nothing. The routes' mounts ask
+         * it before a push's body is read.
+         */
+        admitPush: async (namespace, key) => {
+            await admitted(await adapterOf(), namespace, key);
+        },
+        /** Pushes `body` as `namespace`'s file, with that namespace's push key. */
+        push: async (namespace, key, body) => {
+            const adapter = await adapterOf();
+            const line = namespaceLine(namespace);
+            const opened = await admitted(adapter, namespace, key);
+            try {
+                const bytes = bytesOf(body);
+                if (bytes === undefined || bytes > MAX_POLICIES_BYTES) {
+                    throw new AccessRegistryRefusal("ACCESS_POLICIES_INVALID", bytes === undefined
+                        ? "the pushed body is no JSON a policies file is written in"
+                        : `the pushed file is ${bytes} bytes; the registry takes a policies file of at most ${MAX_POLICIES_BYTES} bytes (1 MiB)`, bytes === undefined ? 400 : 413);
+                }
+                const pushed = pushedOf(body);
+                const stored = () => adapter.transaction(async (inside) => {
+                    const known = await checkOwnership(inside, namespace, pushed);
+                    const file = canonical(pushed.file, checkPolicies, canonicalPolicies);
+                    await checkMarkers(inside, namespace, pushed, known.owners);
+                    await settleBeacons(inside, opened.namespace, pushed.beacons);
+                    if (settings.ownership === "first-push") {
+                        await claim(inside, opened.namespace.id, pushed.file, known.rows);
+                    }
+                    return store(inside, REGISTRY_MODELS.policyRevision, line, file, { namespaceId: opened.namespace.id }, opened.key.id);
+                });
+                try {
+                    return await stored();
+                }
+                catch (error) {
+                    if (error instanceof AccessError) {
+                        throw error;
+                    }
+                    // A push at the same time claimed a Resource this file names, and the
+                    // owners table refused the second claim: checked again against what it
+                    // committed, this push is refused as any claim of an owned Resource is.
+                    const { owners } = await checkOwnership(adapter, namespace, pushed);
+                    await checkMarkers(adapter, namespace, pushed, owners);
+                    throw error;
+                }
+            }
+            catch (error) {
+                if (error instanceof AccessError) {
+                    await log(adapter, {
+                        line,
+                        keyId: opened.key.id,
+                        outcome: "refused",
+                        code: error.code,
+                    });
+                }
+                throw error;
+            }
+        },
+        namespace: keyed(async (adapter, row) => ({
+            name: row.name,
+            createdAt: row.createdAt,
+            head: await headOf(adapter, namespaceLine(row.name)),
+            beacon: (await beaconsOf(adapter, [row.name])).get(row.name) ?? null,
+        })),
+        revisions: keyed(async (adapter, row) => (await atMost(adapter, {
+            model: REGISTRY_MODELS.policyRevision,
+            where: by("namespaceId", row.id),
+            sortBy: { field: "createdAt", direction: "desc" },
+        }, `namespace "${row.name}" has more than ${MANY} revisions, more than the registry lists at once`)).map(({ hash, format, createdAt }) => ({ hash, format, createdAt }))),
+        revision: keyed(async (adapter, row, hash) => HASH.test(hash)
+            ? revisionOf(adapter, REGISTRY_MODELS.policyRevision, hash, row.id)
+            : null),
+        head: keyed(async (adapter, row) => {
+            const hash = await headOf(adapter, namespaceLine(row.name));
+            return hash === null
+                ? null
+                : revisionOf(adapter, REGISTRY_MODELS.policyRevision, hash, row.id);
+        }),
+        /**
+         * What the namespace reads of `owner`: of the Resources its current file reads
+         * as `owner`'s (`{ "foreign": "<owner>" }`), `owner`'s schema entry of each one
+         * `resources` names, and the hash of the beacon `owner` pushed. Anything else
+         * (an owner the file does not read, a Resource it does not read as that
+         * owner's, an owner that does not own it or has no file describing it) gets one
+         * and the same refusal, which tells nothing of who owns what. Every read is
+         * logged with its key.
+         */
+        foreign: async (namespace, key, owner, resources) => {
+            const adapter = await adapterOf();
+            const opened = await authorize(adapter, namespace, key, ["pull", "push"]);
+            const line = namespaceLine(opened.namespace.name);
+            try {
+                const read = await foreignRead(adapter, opened.namespace, owner, unique(resources));
+                await log(adapter, {
+                    line,
+                    keyId: opened.key.id,
+                    outcome: "read",
+                });
+                return read;
+            }
+            catch (error) {
+                if (error instanceof AccessError) {
+                    await log(adapter, {
+                        line,
+                        keyId: opened.key.id,
+                        outcome: "refused",
+                        code: error.code,
+                    });
+                }
+                throw error;
+            }
+        },
+        guardrails: keyed(async (adapter) => {
+            const hash = await headOf(adapter, GUARDRAILS_LINE);
+            return hash === null
+                ? null
+                : revisionOf(adapter, REGISTRY_MODELS.guardrailRevision, hash);
+        }),
+    };
+};