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

package/dist/registry/beacon.ledger.d.ts

@@ -0,0 +1,30 @@
+/** What a push carries: the file, and the beacons its service read (none for a bare file). */
+export type Pushed = {
+    readonly file: unknown;
+    readonly beacons: {
+        readonly [namespace: string]: string;
+    };
+};
+/**
+ * A beacon's hash, as the registry keeps it: of `<namespace>:<value>`, so a value is
+ * bound to the namespace it is pushed for. The same as `beaconHashOf` writes.
+ */
+export declare const storedBeaconHash: (namespace: string, beacon: string) => string;
+/**
+ * A push's body, read: a policies file alone (it has `format`), or the file with the
+ * beacons its service read (`{ file, beacons }`). Anything else in the envelope, a
+ * namespace name that is not one, or a value that is no beacon is refused.
+ */
+export declare const pushedOf: (body: unknown) => Pushed;
+/**
+ * Checks the beacons a push carries against what the registry keeps: each entry
+ * names the pushing namespace or one its file reads, every namespace the file reads
+ * has pushed a beacon, and the push carries that beacon. `registered` holds the
+ * beacon hash each namespace pushed (`null`: none, or no such namespace), at least
+ * for `owners`. The registry runs it before it checks who owns what the file reads.
+ */
+export declare const checkPushedBeacons: (namespace: string, owners: readonly string[], beacons: {
+    readonly [namespace: string]: string;
+}, registered: ReadonlyMap<string, string | null>) => void;
+/** A namespace's own beacon it pushed before and replaced since: a rollback, refused. */
+export declare const beaconRolledBack: (namespace: string) => never;

package/dist/registry/beacon.ledger.js

@@ -0,0 +1,93 @@
+// The registry's side of the ownership beacon: which database each namespace lives
+// in, as the hash of the beacon its service pushed, and the check that a file
+// reading another namespace's Resources as foreign comes from a service that reaches
+// that namespace's database.
+//
+// A push's body is the namespace's policies file, or `{ "file": …, "beacons": { … } }`:
+// the file, and the beacons the service read through its own connection, by
+// namespace. Its own namespace's entry is its own beacon, which the registry keeps
+// (its hash only) as the namespace's; each other entry is the row of a namespace its
+// file reads as foreign, as this service's connection sees it. A file that reads
+// another namespace's Resources is stored only when, for each such namespace, the
+// push carries that namespace's beacon and it hashes to the one that namespace
+// pushed: a service on another database cannot read it. The registry never stores,
+// logs or answers a beacon; a refusal never quotes one.
+import { isBeacon } from "../beacon/beacon.store.js";
+import { isNamespace, isRecord } from "../policies.compiler.js";
+import { sha256Hex } from "../sha256.digest.js";
+import { AccessRegistryRefusal } from "./registry.refusal.js";
+const ENVELOPE_KEYS = ["file", "beacons"];
+const invalid = (message) => {
+    throw new AccessRegistryRefusal("ACCESS_POLICIES_INVALID", message, 400);
+};
+/**
+ * A beacon's hash, as the registry keeps it: of `<namespace>:<value>`, so a value is
+ * bound to the namespace it is pushed for. The same as `beaconHashOf` writes.
+ */
+export const storedBeaconHash = (namespace, beacon) => `sha256:${sha256Hex(`${namespace}:${beacon}`)}`;
+/**
+ * A push's body, read: a policies file alone (it has `format`), or the file with the
+ * beacons its service read (`{ file, beacons }`). Anything else in the envelope, a
+ * namespace name that is not one, or a value that is no beacon is refused.
+ */
+export const pushedOf = (body) => {
+    if (!isRecord(body) || !("file" in body) || "format" in body) {
+        return { file: body, beacons: {} };
+    }
+    const unknown = Object.keys(body).filter((key) => !ENVELOPE_KEYS.includes(key));
+    if (unknown.length > 0) {
+        invalid(`a push is the policies file, or \`{ file, beacons }\`; it does not take ${unknown.map((key) => `\`${key}\``).join(", ")}`);
+    }
+    const beacons = body.beacons ?? {};
+    if (!isRecord(beacons)) {
+        invalid("`beacons` maps a namespace to its beacon, as this service's connection reads its row in _aventara_beacon");
+    }
+    for (const [namespace, beacon] of Object.entries(beacons)) {
+        if (!isNamespace(namespace)) {
+            invalid(`\`beacons\` names ${JSON.stringify(namespace)}, which is not a namespace name`);
+        }
+        if (!isBeacon(beacon)) {
+            invalid(`\`beacons\` holds no beacon for namespace "${namespace}" (avb_ and 43 base64url characters)`);
+        }
+    }
+    return {
+        file: body.file,
+        beacons: beacons,
+    };
+};
+/** Why a file reading `owner`'s Resources is refused, beside the fix the refusal names. */
+const crossDatabase = (message) => {
+    throw new AccessRegistryRefusal("ACCESS_FOREIGN_CROSS_DATABASE", `${message}. A foreign Resource is read only while both services share one database; across databases, carry the fact in a JWT claim instead (\`policies.claims\`)`, 403);
+};
+/**
+ * Checks the beacons a push carries against what the registry keeps: each entry
+ * names the pushing namespace or one its file reads, every namespace the file reads
+ * has pushed a beacon, and the push carries that beacon. `registered` holds the
+ * beacon hash each namespace pushed (`null`: none, or no such namespace), at least
+ * for `owners`. The registry runs it before it checks who owns what the file reads.
+ */
+export const checkPushedBeacons = (namespace, owners, beacons, registered) => {
+    for (const named of Object.keys(beacons)) {
+        if (named !== namespace && !owners.includes(named)) {
+            invalid(`\`beacons\` names namespace "${named}", whose Resources the file does not read: a push carries its own namespace's beacon and those of the namespaces it reads as foreign`);
+        }
+    }
+    // The same refusal whether the owner exists, has pushed a beacon, or owns what the
+    // file reads: a service that cannot show it shares the owner's database learns
+    // nothing of the registry's namespaces from it.
+    for (const owner of owners) {
+        const pushed = registered.get(owner) ?? null;
+        const carried = beacons[owner];
+        if (carried === undefined) {
+            crossDatabase(`the file reads namespace "${owner}"'s Resources as foreign, and the push carries no beacon of "${owner}" as this service's connection reads it: push with \`avaccess push --beacon <module>\``);
+        }
+        if (pushed === null ||
+            storedBeaconHash(owner, carried) !== pushed) {
+            crossDatabase(`the file reads namespace "${owner}"'s Resources as foreign, and "${owner}"'s beacon as this service's connection reads it is not one "${owner}" pushed: the two services are on different databases, or "${owner}"'s service has not pushed its file with \`avaccess push --beacon <module>\` yet`);
+        }
+    }
+};
+/** A namespace's own beacon it pushed before and replaced since: a rollback, refused. */
+export const beaconRolledBack = (namespace) => {
+    throw new AccessRegistryRefusal("ACCESS_BEACON_MISMATCH", `the push carries, as namespace "${namespace}"'s own beacon, one it pushed before and has replaced since: a beacon never comes back (an old database's row, or a replayed push). An operator verifies which database "${namespace}" runs on, and deletes the old row there; the next push writes a new one`, 409);
+};

package/dist/registry/ownership.check.d.ts

@@ -0,0 +1,54 @@
+import { type AccessGuardrails } from "../guardrails/guardrails-contract.js";
+import type { AccessPolicies } from "../policies-contract.js";
+/** Who owns each Resource the registry knows of: Resource name → namespace. */
+type ResourceOwners = ReadonlyMap<string, string>;
+/**
+ * How a Resource comes to be owned: by the first push that names it as its own
+ * (`first-push`, the default), or only by the operator's `assignResource`
+ * (`assigned`).
+ */
+export type OwnershipMode = "first-push" | "assigned";
+/** The Resources a file names as its own: its schema entries not marked foreign. */
+export declare const ownResources: (file: AccessPolicies) => readonly string[];
+/**
+ * Every Resource a file names, read defensively: its schema's, and those its grants,
+ * denies and governed fields name. The registry looks up the owners of these only.
+ */
+export declare const resourcesNamed: (file: unknown) => readonly string[];
+/** The namespaces a file's foreign markers name, read defensively. */
+export declare const foreignNamespaces: (file: unknown) => readonly string[];
+/**
+ * Checks a file pushed to `namespace`: it is that namespace's file, it claims no
+ * Resource another namespace owns (and, with `assigned` ownership, only Resources
+ * the operator assigned to it), and its grants, denies and governed fields name only
+ * its own Resources. Throws `ACCESS_OWNERSHIP` naming the rule; the owner only when
+ * the file itself names it. `owners` holds at least every Resource the file names
+ * (`resourcesNamed`). Its foreign markers are checked apart
+ * ({@link checkForeignMarkers}), once the push's beacons have shown it shares each
+ * owner's database.
+ */
+export declare const checkNamespaceOwnership: (namespace: string, file: unknown, owners: ResourceOwners, ownership?: OwnershipMode) => void;
+/**
+ * Checks a file's foreign markers: each names a namespace the registry has, and the
+ * one that owns the Resource when it has an owner. Throws `ACCESS_OWNERSHIP`. The
+ * registry asks it only after the push's beacons showed the service shares each
+ * marked namespace's database (`checkPushedBeacons`): before that, its answer would
+ * tell any service which namespaces exist and who owns what. `owners` holds at least
+ * every Resource the file names, and `namespaces` at least every namespace its
+ * markers name that the registry has.
+ */
+export declare const checkForeignMarkers: (namespace: string, file: unknown, owners: ResourceOwners, namespaces: ReadonlySet<string>) => void;
+/**
+ * Checks the org's guardrails file grants nothing: it holds no `grants` and no
+ * guardrail with `subjects`. Throws `ACCESS_OWNERSHIP` naming what grants. (The
+ * format's own checks, which run after this, refuse every other member it does not
+ * define.)
+ */
+export declare const checkGuardrailsOwnership: (file: unknown) => void;
+/**
+ * Checks every namespace a guardrail names a Resource list for is one the registry
+ * has: a guardrail for a misspelled namespace would narrow nothing. Throws
+ * `ACCESS_NAMESPACE` naming the guardrail and the namespace.
+ */
+export declare const checkGuardrailNamespaces: (file: AccessGuardrails, namespaces: ReadonlySet<string>) => void;
+export {};

package/dist/registry/ownership.check.js

@@ -0,0 +1,215 @@
+// Ownership at push. The data owner writes the grants: a namespace's file names as
+// its own only Resources no other namespace owns, and its grants, denies and
+// governed fields name only those. A Resource another namespace owns appears in the
+// file as `{ "foreign": "<owner>" }` and is read in conditions only. The org's
+// guardrails file (`guardrails@1`) holds no grant: central Access may only narrow.
+//
+// The builder's types and the compiler already refuse most of this for a file
+// written with `definePolicies`; a hand-written file gets past both, so the registry
+// checks every pushed file again, against what the namespaces' current files claim.
+// The checks read the file defensively: anything malformed is left to the compiler's
+// checks, which run after these.
+import { AccessError } from "../access/access.error.js";
+import { GUARDRAILS_FORMAT, } from "../guardrails/guardrails-contract.js";
+import { isRecord } from "../policies.compiler.js";
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OWNERSHIP", message);
+};
+const listOf = (value) => Array.isArray(value) ? value : [];
+const ruleId = (rule) => typeof rule.id === "string" ? `"${rule.id}"` : "(no id)";
+/** The Resources a file names as its own: its schema entries not marked foreign. */
+export const ownResources = (file) => Object.entries(file.schema)
+    .filter(([, facts]) => facts.foreign === undefined)
+    .map(([resource]) => resource);
+/** The Resource a field reference (`Resource.field`) is on, or `""`. */
+const resourceOfField = (field) => typeof field === "string" && field.includes(".")
+    ? field.slice(0, field.indexOf("."))
+    : "";
+/**
+ * Every Resource a file names, read defensively: its schema's, and those its grants,
+ * denies and governed fields name. The registry looks up the owners of these only.
+ */
+export const resourcesNamed = (file) => {
+    if (!isRecord(file)) {
+        return [];
+    }
+    const named = new Set(Object.keys(isRecord(file.schema) ? file.schema : {}));
+    for (const rule of [...listOf(file.grants), ...listOf(file.denies)]) {
+        if (!isRecord(rule)) {
+            continue;
+        }
+        if (typeof rule.resource === "string" && rule.resource !== "*") {
+            named.add(rule.resource);
+        }
+        for (const field of listOf(rule.fields)) {
+            const resource = resourceOfField(field);
+            if (resource !== "") {
+                named.add(resource);
+            }
+        }
+    }
+    for (const resource of Object.keys(isRecord(file.govern) ? file.govern : {})) {
+        named.add(resource);
+    }
+    return [...named];
+};
+/** The namespaces a file's foreign markers name, read defensively. */
+export const foreignNamespaces = (file) => {
+    const schema = isRecord(file) && isRecord(file.schema) ? file.schema : {};
+    const named = new Set();
+    for (const facts of Object.values(schema)) {
+        const foreign = isRecord(facts) ? facts.foreign : undefined;
+        if (typeof foreign === "string") {
+            named.add(foreign);
+        }
+    }
+    return [...named];
+};
+const owns = (owner) => owner.named === undefined
+    ? "another namespace owns"
+    : `namespace "${owner.named}" owns`;
+const askOwner = (owner) => owner.named === undefined ? "its owner" : `"${owner.named}"`;
+/**
+ * Checks a file pushed to `namespace`: it is that namespace's file, it claims no
+ * Resource another namespace owns (and, with `assigned` ownership, only Resources
+ * the operator assigned to it), and its grants, denies and governed fields name only
+ * its own Resources. Throws `ACCESS_OWNERSHIP` naming the rule; the owner only when
+ * the file itself names it. `owners` holds at least every Resource the file names
+ * (`resourcesNamed`). Its foreign markers are checked apart
+ * ({@link checkForeignMarkers}), once the push's beacons have shown it shares each
+ * owner's database.
+ */
+export const checkNamespaceOwnership = (namespace, file, owners, ownership = "first-push") => {
+    if (!isRecord(file)) {
+        return;
+    }
+    if (file.namespace !== namespace) {
+        refuse(file.namespace === undefined
+            ? `the file pushed to namespace "${namespace}" names no namespace. Compile it with definePolicies(model, { namespace: "${namespace}" })`
+            : `the file pushed to namespace "${namespace}" is namespace ${JSON.stringify(file.namespace)}'s. A namespace's key pushes only its own file`);
+    }
+    const schema = isRecord(file.schema) ? file.schema : {};
+    /** The namespace that owns `resource`, when it is not this one; `undefined` when it is. */
+    const ownerOf = (resource) => {
+        const facts = schema[resource];
+        const foreign = isRecord(facts) ? facts.foreign : undefined;
+        if (typeof foreign === "string") {
+            return { named: foreign };
+        }
+        const owner = owners.get(resource);
+        return owner === undefined || owner === namespace
+            ? undefined
+            : { named: undefined };
+    };
+    for (const [resource, facts] of Object.entries(schema)) {
+        const foreign = isRecord(facts) ? facts.foreign : undefined;
+        const owner = owners.get(resource);
+        if (foreign === undefined) {
+            if (owner !== undefined && owner !== namespace) {
+                refuse(`namespace "${namespace}" names ${resource} as its own, and another namespace owns it. Mark it { "foreign": "<its owner>" } to read it in conditions; the registry's operator can tell you which namespace owns it`);
+            }
+            if (owner === undefined && ownership === "assigned") {
+                refuse(`namespace "${namespace}" names ${resource} as its own, and the operator has not assigned ${resource} to it. This registry takes ownership from its operator (\`ownership: "assigned"\`): ask them to run access.registry.assignResource("${resource}", "${namespace}")`);
+            }
+        }
+    }
+    for (const grant of listOf(file.grants)) {
+        if (!isRecord(grant)) {
+            continue;
+        }
+        const resource = grant.resource;
+        const owner = typeof resource === "string" && resource !== "*"
+            ? ownerOf(resource)
+            : undefined;
+        if (owner !== undefined) {
+            refuse(`grant ${ruleId(grant)} in namespace "${namespace}" names ${String(resource)}, which ${owns(owner)}. A namespace grants only on its own Resources. Ask ${askOwner(owner)} to add the grant, or add a deny guardrail on the Access server`);
+        }
+        for (const field of listOf(grant.fields)) {
+            const fieldResource = resourceOfField(field);
+            const fieldOwner = fieldResource === "" ? undefined : ownerOf(fieldResource);
+            if (fieldOwner !== undefined) {
+                refuse(`grant ${ruleId(grant)} in namespace "${namespace}" opens ${String(field)}, a field of ${fieldResource}, which ${owns(fieldOwner)}. A namespace grants only on its own Resources`);
+            }
+        }
+    }
+    for (const deny of listOf(file.denies)) {
+        if (!isRecord(deny)) {
+            continue;
+        }
+        const resource = deny.resource;
+        const owner = typeof resource === "string" && resource !== "*"
+            ? ownerOf(resource)
+            : undefined;
+        if (owner !== undefined) {
+            refuse(`deny ${ruleId(deny)} in namespace "${namespace}" names ${String(resource)}, which ${owns(owner)}. A namespace's denies narrow only its own Resources; narrowing another namespace's is an org guardrail`);
+        }
+    }
+    for (const resource of Object.keys(isRecord(file.govern) ? file.govern : {})) {
+        const owner = ownerOf(resource);
+        if (owner !== undefined) {
+            refuse(`namespace "${namespace}" governs fields of ${resource}, which ${owns(owner)}. Only the owner governs a Resource's fields`);
+        }
+    }
+};
+/**
+ * Checks a file's foreign markers: each names a namespace the registry has, and the
+ * one that owns the Resource when it has an owner. Throws `ACCESS_OWNERSHIP`. The
+ * registry asks it only after the push's beacons showed the service shares each
+ * marked namespace's database (`checkPushedBeacons`): before that, its answer would
+ * tell any service which namespaces exist and who owns what. `owners` holds at least
+ * every Resource the file names, and `namespaces` at least every namespace its
+ * markers name that the registry has.
+ */
+export const checkForeignMarkers = (namespace, file, owners, namespaces) => {
+    const schema = isRecord(file) && isRecord(file.schema) ? file.schema : {};
+    for (const [resource, facts] of Object.entries(schema)) {
+        const foreign = isRecord(facts) ? facts.foreign : undefined;
+        if (typeof foreign !== "string") {
+            continue;
+        }
+        if (!namespaces.has(foreign)) {
+            refuse(`namespace "${namespace}" marks ${resource} foreign to "${foreign}", which is not a namespace of this registry`);
+        }
+        const owner = owners.get(resource);
+        if (owner !== undefined && owner !== foreign) {
+            refuse(`namespace "${namespace}" marks ${resource} foreign to "${foreign}", which does not own it`);
+        }
+    }
+};
+/**
+ * Checks the org's guardrails file grants nothing: it holds no `grants` and no
+ * guardrail with `subjects`. Throws `ACCESS_OWNERSHIP` naming what grants. (The
+ * format's own checks, which run after this, refuse every other member it does not
+ * define.)
+ */
+export const checkGuardrailsOwnership = (file) => {
+    // A file of another format is refused by the format's checks, by its format.
+    if (!isRecord(file) || file.format !== GUARDRAILS_FORMAT) {
+        return;
+    }
+    if (file.grants !== undefined) {
+        refuse(`the org's guardrails file holds "grants". Guardrails only deny; a grant belongs in the file of the namespace that owns its Resource`);
+    }
+    for (const guardrail of listOf(file.denies)) {
+        if (isRecord(guardrail) && guardrail.subjects !== undefined) {
+            refuse(`guardrail ${ruleId(guardrail)} in the org's guardrails file names subjects, as a grant does. Guardrails only deny; a grant belongs in the file of the namespace that owns its Resource`);
+        }
+    }
+};
+/**
+ * Checks every namespace a guardrail names a Resource list for is one the registry
+ * has: a guardrail for a misspelled namespace would narrow nothing. Throws
+ * `ACCESS_NAMESPACE` naming the guardrail and the namespace.
+ */
+export const checkGuardrailNamespaces = (file, namespaces) => {
+    for (const guardrail of file.denies) {
+        if (guardrail.resources === "*") {
+            continue;
+        }
+        for (const namespace of Object.keys(guardrail.resources)) {
+            if (!namespaces.has(namespace)) {
+                throw new AccessError("ACCESS_NAMESPACE", `guardrail "${guardrail.id}" names Resources of namespace "${namespace}", which this registry does not have; a guardrail on a namespace that does not exist would narrow nothing. createNamespace adds it, or correct the guardrail`);
+            }
+        }
+    }
+};

package/dist/registry/registry.endpoints.d.ts

@@ -0,0 +1,50 @@
+import { type Registry } from "./access.registry.js";
+/** Where every registry route is, under Better Auth's `basePath`: no other plugin's route may be. */
+export declare const REGISTRY_ROUTES = "/access/v1";
+/** The registry routes' prefix, under Better Auth's `basePath`. */
+export declare const REGISTRY_PATH = "/access/v1/namespaces";
+/** The route that names the namespace a key belongs to, under Better Auth's `basePath`. */
+export declare const KEY_OWNER_PATH = "/access/v1/key";
+/** Every registry route's path, under Better Auth's `basePath`, as its endpoint declares it. */
+export declare const REGISTRY_ROUTE_PATHS: readonly ["/access/v1/namespaces/:ns", "/access/v1/namespaces/:ns/revisions", "/access/v1/namespaces/:ns/revisions/:hash", "/access/v1/namespaces/:ns/head", "/access/v1/namespaces/:ns/guardrails", "/access/v1/namespaces/:ns/foreign/:owner", "/access/v1/key"];
+/** The registry's endpoints by name, as Better Auth keys them (`auth.api.<name>`): no other plugin's endpoint may take one. */
+export declare const REGISTRY_ENDPOINT_NAMES: readonly ["accessNamespace", "accessRevisions", "accessRevision", "accessHead", "accessGuardrails", "accessForeign", "accessKeyOwner", "accessPush"];
+/** The request header that carries a registry key. */
+export declare const KEY_HEADER = "x-access-key";
+/** What a registry endpoint reads of Better Auth's endpoint context. */
+type EndpointContext = {
+    readonly params: {
+        readonly [name: string]: string | undefined;
+    };
+    readonly query?: {
+        readonly [name: string]: string | readonly string[] | undefined;
+    } | undefined;
+    readonly headers?: Headers | undefined;
+    readonly body?: unknown;
+};
+/** Better Auth's `createAuthEndpoint`, as the registry calls it. */
+export type EndpointFactory = (path: string, options: {
+    readonly method: "GET" | "POST";
+}, handler: (context: EndpointContext) => Promise<Response>) => unknown;
+/**
+ * The registry's `onRequest`, which Better Auth's router runs on every request
+ * before a route reads its body: a push (`POST …/namespaces/:ns/revisions`) whose
+ * declared length is over {@link MAX_PUSH_BODY_BYTES} is answered `413`, and one
+ * whose key is not the namespace's push key is answered the refusal the route would
+ * give, both before the body is read, on any mount. Anything else goes on.
+ */
+export declare const registryOnRequest: (registry: Registry) => (request: Request, context: unknown) => Promise<{
+    readonly response: Response;
+} | undefined>;
+/** The registry's endpoints, keyed as Better Auth keys a plugin's (`access.api.<key>`). */
+export declare const registryEndpoints: (registry: Registry, endpoint: EndpointFactory) => {
+    accessNamespace: unknown;
+    accessRevisions: unknown;
+    accessRevision: unknown;
+    accessHead: unknown;
+    accessGuardrails: unknown;
+    accessForeign: unknown;
+    accessKeyOwner: unknown;
+    accessPush: unknown;
+};
+export {};

package/dist/registry/registry.endpoints.js

@@ -0,0 +1,193 @@
+// The registry's HTTP routes, as Better Auth plugin endpoints: Better Auth's router
+// serves them under its `basePath` beside its own routes, so `access.handler` carries
+// them and every mount of it (a Next.js route file, a Node.js handler, `serve`) serves
+// them with no wiring of its own. Each one is thin: it reads the key header, the path
+// and the body, asks the registry, and writes the answer or the refusal as JSON.
+//
+//   GET  /access/v1/namespaces/:ns                    the namespace and its head's hash
+//   GET  /access/v1/namespaces/:ns/revisions          its revisions, newest first
+//   GET  /access/v1/namespaces/:ns/revisions/:hash    one revision, with its file
+//   GET  /access/v1/namespaces/:ns/head               the current revision, with its file
+//   GET  /access/v1/namespaces/:ns/guardrails         the org's current guardrails file
+//   GET  /access/v1/namespaces/:ns/foreign/:owner     what :ns reads of :owner as foreign:
+//                                                     its beacon's hash, and its entry of
+//                                                     each Resource `?resources=A,B` names
+//   POST /access/v1/namespaces/:ns/revisions          push: the body is the namespace's file
+//   GET  /access/v1/key                               the namespace the key belongs to, and its kind
+//
+// The key travels in the `x-access-key` header, as Better Auth's API keys travel in
+// `x-api-key`: a pull or push key for the reads, the push key for a push. Revisions
+// are never updated, so no route writes to one.
+import { AccessError } from "../access/access.error.js";
+import { AccessRegistryRefusal, MAX_POLICIES_BYTES, } from "./access.registry.js";
+/** Where every registry route is, under Better Auth's `basePath`: no other plugin's route may be. */
+export const REGISTRY_ROUTES = "/access/v1";
+/** The registry routes' prefix, under Better Auth's `basePath`. */
+export const REGISTRY_PATH = `${REGISTRY_ROUTES}/namespaces`;
+/** The route that names the namespace a key belongs to, under Better Auth's `basePath`. */
+export const KEY_OWNER_PATH = `${REGISTRY_ROUTES}/key`;
+/** Every registry route's path, under Better Auth's `basePath`, as its endpoint declares it. */
+export const REGISTRY_ROUTE_PATHS = [
+    `${REGISTRY_PATH}/:ns`,
+    `${REGISTRY_PATH}/:ns/revisions`,
+    `${REGISTRY_PATH}/:ns/revisions/:hash`,
+    `${REGISTRY_PATH}/:ns/head`,
+    `${REGISTRY_PATH}/:ns/guardrails`,
+    `${REGISTRY_PATH}/:ns/foreign/:owner`,
+    KEY_OWNER_PATH,
+];
+/** The registry's endpoints by name, as Better Auth keys them (`auth.api.<name>`): no other plugin's endpoint may take one. */
+export const REGISTRY_ENDPOINT_NAMES = [
+    "accessNamespace",
+    "accessRevisions",
+    "accessRevision",
+    "accessHead",
+    "accessGuardrails",
+    "accessForeign",
+    "accessKeyOwner",
+    "accessPush",
+];
+/** The request header that carries a registry key. */
+export const KEY_HEADER = "x-access-key";
+const json = (status, body) => new Response(JSON.stringify(body), {
+    status,
+    headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+    },
+});
+const STATUS_OF = {
+    ACCESS_OWNERSHIP: 403,
+    ACCESS_POLICIES_INVALID: 400,
+    ACCESS_NAMESPACE: 404,
+};
+/** A refusal as JSON: `{ code, message }`, as Better Auth answers its own. */
+const refusal = (error) => {
+    if (error instanceof AccessError) {
+        const status = error instanceof AccessRegistryRefusal
+            ? error.status
+            : (STATUS_OF[error.code] ?? 400);
+        return json(status, { code: error.code, message: error.message });
+    }
+    throw error;
+};
+/** A path segment as sent: Better Auth's router hands it over still percent-encoded. */
+const decoded = (segment) => {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+};
+const notFound = (message) => json(404, { code: "NOT_FOUND", message: `Aventara Access: ${message}` });
+/**
+ * The most a push's body may declare before it is read: twice the largest file the
+ * registry stores, which leaves room for the beacons beside it and for formatting.
+ * A longer declared length is refused unread; the registry still holds the file to
+ * its own cap once it is read.
+ */
+const MAX_PUSH_BODY_BYTES = 2 * MAX_POLICIES_BYTES;
+/** A push's route under the base path, the namespace its one segment. */
+const PUSH_ROUTE = new RegExp(`^${REGISTRY_PATH}/([^/]+)/revisions/?$`, "i");
+/** The path Better Auth's router strips before it routes: its base URL's path. */
+const basePathOf = (context) => {
+    const { baseURL, options } = (context ?? {});
+    try {
+        return new URL(String(baseURL)).pathname.replace(/\/+$/, "");
+    }
+    catch {
+        const basePath = options?.basePath;
+        return (typeof basePath === "string" ? basePath : "/api/auth").replace(/\/+$/, "");
+    }
+};
+/**
+ * The registry's `onRequest`, which Better Auth's router runs on every request
+ * before a route reads its body: a push (`POST …/namespaces/:ns/revisions`) whose
+ * declared length is over {@link MAX_PUSH_BODY_BYTES} is answered `413`, and one
+ * whose key is not the namespace's push key is answered the refusal the route would
+ * give, both before the body is read, on any mount. Anything else goes on.
+ */
+export const registryOnRequest = (registry) => async (request, context) => {
+    if (request.method !== "POST") {
+        return undefined;
+    }
+    let pathname;
+    try {
+        pathname = new URL(request.url).pathname;
+    }
+    catch {
+        return undefined;
+    }
+    const base = basePathOf(context);
+    if (base !== "" && !pathname.startsWith(`${base}/`)) {
+        return undefined;
+    }
+    const namespace = PUSH_ROUTE.exec(pathname.slice(base.length))?.[1];
+    if (namespace === undefined) {
+        return undefined;
+    }
+    const declared = Number(request.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_PUSH_BODY_BYTES) {
+        return {
+            response: json(413, {
+                code: "ACCESS_POLICIES_INVALID",
+                message: `Aventara Access: the push's body is ${declared} bytes; the registry reads a push of at most ${MAX_PUSH_BODY_BYTES} bytes, and stores a policies file of at most ${MAX_POLICIES_BYTES} (1 MiB)`,
+            }),
+        };
+    }
+    try {
+        await registry.admitPush(namespace, request.headers.get(KEY_HEADER) ?? undefined);
+    }
+    catch (error) {
+        return { response: refusal(error) };
+    }
+    return undefined;
+};
+/** The registry's endpoints, keyed as Better Auth keys a plugin's (`access.api.<key>`). */
+export const registryEndpoints = (registry, endpoint) => {
+    const route = (answer) => async (context) => {
+        try {
+            return await answer(context, context.headers?.get(KEY_HEADER) ?? undefined, context.params.ns ?? "");
+        }
+        catch (error) {
+            return refusal(error);
+        }
+    };
+    const endpoints = {
+        accessNamespace: endpoint(REGISTRY_ROUTE_PATHS[0], { method: "GET" }, route(async (_, key, namespace) => json(200, await registry.namespace(namespace, key)))),
+        accessRevisions: endpoint(REGISTRY_ROUTE_PATHS[1], { method: "GET" }, route(async (_, key, namespace) => json(200, { revisions: await registry.revisions(namespace, key) }))),
+        accessRevision: endpoint(REGISTRY_ROUTE_PATHS[2], { method: "GET" }, route(async (context, key, namespace) => {
+            const hash = decoded(context.params.hash ?? "");
+            const revision = await registry.revision(namespace, key, hash);
+            return revision === null
+                ? notFound(`namespace "${namespace}" has no revision ${JSON.stringify(hash)}`)
+                : json(200, revision);
+        })),
+        accessHead: endpoint(REGISTRY_ROUTE_PATHS[3], { method: "GET" }, route(async (_, key, namespace) => {
+            const head = await registry.head(namespace, key);
+            return head === null
+                ? notFound(`namespace "${namespace}" has no file pushed yet`)
+                : json(200, head);
+        })),
+        accessGuardrails: endpoint(REGISTRY_ROUTE_PATHS[4], { method: "GET" }, route(async (_, key, namespace) => {
+            const guardrails = await registry.guardrails(namespace, key);
+            return guardrails === null
+                ? notFound("the org has no guardrails file pushed yet")
+                : json(200, guardrails);
+        })),
+        accessForeign: endpoint(REGISTRY_ROUTE_PATHS[5], { method: "GET" }, route(async (context, key, namespace) => {
+            const asked = context.query?.resources;
+            const resources = (asked === undefined ? [] : typeof asked === "string" ? [asked] : asked)
+                .flatMap((list) => String(list).split(","))
+                .filter((name) => name !== "");
+            return json(200, await registry.foreign(namespace, key, decoded(context.params.owner ?? ""), resources));
+        })),
+        accessKeyOwner: endpoint(REGISTRY_ROUTE_PATHS[6], { method: "GET" }, route(async (_, key) => json(200, await registry.keyOwner(key)))),
+        accessPush: endpoint(REGISTRY_ROUTE_PATHS[1], { method: "POST" }, route(async (context, key, namespace) => {
+            const pushed = await registry.push(namespace, key, context.body);
+            return json(pushed.created ? 201 : 200, { namespace, ...pushed });
+        })),
+    };
+    return endpoints;
+};

package/dist/registry/registry.key.d.ts

@@ -0,0 +1,7 @@
+/** What a registry key may do: `push` pushes the namespace's file and reads; `pull` only reads. */
+export type AccessKeyKind = "push" | "pull";
+export declare const KEY_KINDS: readonly AccessKeyKind[];
+/** A new key of `kind`: 256 random bits from the runtime's CSPRNG. */
+export declare const newKey: (kind: AccessKeyKind) => string;
+/** The hash the registry stores and looks a key up by; `undefined` for text that is no key. */
+export declare const keyHashOf: (key: string) => string | undefined;