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

package/dist/aventara-where.translator.d.ts

@@ -0,0 +1,19 @@
+import type { AccessComparison } from "./policies-contract.js";
+import type { Resolved } from "./scope.resolver.js";
+/** A fragment of Aventara's `where` (core's `AvPolicyWhere`, by shape). */
+export type AccessWhere = {
+    readonly [key: string]: unknown;
+};
+/** The Aventara filter operator a comparison is written with. */
+export declare const operatorOf: (cmp: AccessComparison) => string;
+/**
+ * Sets `key` on `target` as its own data member. An assignment would read
+ * `__proto__` as the prototype setter and drop the condition.
+ */
+export declare const defineMember: (target: Record<string, unknown>, key: string, value: unknown) => void;
+/** Merges fragments into one object when no key repeats; otherwise `undefined`. */
+export declare const mergeWhere: (fragments: readonly AccessWhere[]) => AccessWhere | undefined;
+/** Translates a row condition that is neither `true` nor `false` at its root. */
+export declare const translateWhere: (node: Resolved) => AccessWhere;
+/** A seam answer: `true` every row, `false` none, or a `where`. */
+export declare const translateAnswer: (node: Resolved) => boolean | AccessWhere;

package/dist/aventara-where.translator.js

@@ -0,0 +1,87 @@
+// Folded condition → Aventara's `where` grammar, with explicit operators
+// (`{ equals: … }`), as core validates it against the Core Contract.
+const OPERATOR = {
+    eq: "equals",
+    ne: "not",
+    in: "in",
+    notIn: "notIn",
+};
+/** The Aventara filter operator a comparison is written with. */
+export const operatorOf = (cmp) => OPERATOR[cmp];
+const isField = (node) => node.k === "cmp" ||
+    node.k === "rel" ||
+    node.k === "some" ||
+    node.k === "every" ||
+    node.k === "none";
+const keyOf = (node) => (node.k === "cmp" ? node.field : node.relation);
+/**
+ * Sets `key` on `target` as its own data member. An assignment would read
+ * `__proto__` as the prototype setter and drop the condition.
+ */
+export const defineMember = (target, key, value) => {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+};
+/** An object with one own member. */
+const one = (key, value) => {
+    const where = {};
+    defineMember(where, key, value);
+    return where;
+};
+/** Merges fragments into one object when no key repeats; otherwise `undefined`. */
+export const mergeWhere = (fragments) => {
+    const merged = {};
+    for (const fragment of fragments) {
+        for (const [key, value] of Object.entries(fragment)) {
+            if (Object.hasOwn(merged, key)) {
+                return undefined;
+            }
+            defineMember(merged, key, value);
+        }
+    }
+    return merged;
+};
+/** Translates a row condition that is neither `true` nor `false` at its root. */
+export const translateWhere = (node) => {
+    switch (node.k) {
+        case "true":
+            return {};
+        case "false":
+            // Aventara's `where` has no `false`: the empty `OR` is its one way to match no
+            // row, and an ORM reads it so.
+            return { OR: [] };
+        case "cmp":
+            return one(node.field, {
+                [operatorOf(node.cmp)]: Array.isArray(node.value)
+                    ? [...node.value]
+                    : node.value,
+            });
+        case "rel":
+            return one(node.relation, translateWhere(node.where));
+        case "some":
+        case "every":
+        case "none":
+            return one(node.relation, { [node.k]: translateWhere(node.where) });
+        case "not":
+            return { NOT: translateWhere(node.arg) };
+        case "or":
+            return { OR: node.args.map(translateWhere) };
+        case "all":
+            return { AND: node.args.map(translateWhere) };
+        case "and": {
+            // Written by the author as one object: written back as one when every part is
+            // a field condition and no field repeats.
+            if (node.args.every(isField) &&
+                new Set(node.args.map(keyOf)).size === node.args.length) {
+                return mergeWhere(node.args.map(translateWhere));
+            }
+            return { AND: node.args.map(translateWhere) };
+        }
+    }
+};
+/** A seam answer: `true` every row, `false` none, or a `where`. */
+export const translateAnswer = (node) => node.k === "true" ? true : node.k === "false" ? false : translateWhere(node);

package/dist/beacon/beacon.check.d.ts

@@ -0,0 +1,59 @@
+/** Reads a namespace's beacon row, through the service's own connection. */
+export type AccessBeaconReader = {
+    /**
+     * The `value` of `namespace`'s row in `_aventara_beacon`, as this service's
+     * connection reads it; `null` when there is none.
+     */
+    read(namespace: string): Promise<string | null>;
+};
+/**
+ * One environment's beacon pins, `avAccess.beacons.<environment>.json` as
+ * `avaccess pull --env <environment>` writes it: the hash of the beacon each
+ * namespace the rules read as foreign pushed from that environment's database.
+ * `format` is typed as a string so the file imported as JSON is one as it is.
+ */
+export type AccessBeaconPins = {
+    /** `"aventara-access/beacons@1"`. */
+    readonly format: string;
+    /** The namespace that reads the others: the lock's. */
+    readonly namespace: string;
+    /** The environment the pins were pulled for: `production`, `staging`, … */
+    readonly environment: string;
+    /** Each owner namespace's beacon hash, `sha256:<hex>`. */
+    readonly beacons: {
+        readonly [namespace: string]: string;
+    };
+};
+/** The format marker of every beacon pins file. */
+export declare const BEACON_PINS_FORMAT = "aventara-access/beacons@1";
+/**
+ * The error a generated client throws when its beacons have not passed, shaped as
+ * `AccessError` is (`name`, `code`, a message that starts `Aventara Access:`): the
+ * client imports nothing, so it cannot throw the class itself.
+ */
+export declare const beaconMismatch: (message: string) => Error & {
+    readonly code: "ACCESS_BEACON_MISMATCH";
+};
+/** A beacon: `avb_` and 32 random bytes in base64url. */
+export declare const BEACON: RegExp;
+/** A pinned beacon hash: `sha256:` and 64 lowercase hex digits. */
+export declare const BEACON_HASH: RegExp;
+/**
+ * A beacon's hash, as the registry and the pins name it: `sha256:<hex>` of
+ * `<namespace>:<value>`. The namespace is bound in: a value registered under one
+ * namespace never matches, or collides with, another namespace's beacon.
+ */
+export declare const beaconHashOf: (namespace: string, value: string) => Promise<string>;
+/**
+ * What is wrong with `pins` as `namespace`'s beacon pins of `environment` for the
+ * `owners` its rules read as foreign: its format and members, its namespace, its
+ * environment, a `sha256:` hash for every owner; `undefined` when nothing is.
+ */
+export declare const beaconPinsProblem: (namespace: string, owners: readonly string[], pins: unknown, environment: unknown) => string | undefined;
+/**
+ * What is wrong with the beacons of `owners` (the namespaces `namespace`'s rules
+ * read as foreign), held to `pins` (which must be `environment`'s) and read through
+ * `reader`; `undefined` when every
+ * owner's row is there and hashes to its pin. Each owner is read once, in order.
+ */
+export declare const beaconProblem: (namespace: string, owners: readonly string[], pins: unknown, environment: unknown, reader: AccessBeaconReader) => Promise<string | undefined>;

package/dist/beacon/beacon.check.js

@@ -0,0 +1,128 @@
+// The ownership beacon's check, as a service runs it when it starts: each namespace
+// whose Resources the rules read as `foreign` has one row in `_aventara_beacon`,
+// written once by that namespace's own service with a random value, and the
+// registry knows the value's hash. A database's beacons are its own, so their
+// hashes are pinned per environment, apart from `avAccess.lock.json` (which holds
+// against any registry): `avaccess pull --env <name>` writes them to
+// `avAccess.beacons.<name>.json` (`AccessBeaconPins`), or the deploy hands the same
+// object in from its environment. At startup the service reads each owner's row
+// through its own connection: the row is there and hashes to the pin only when the
+// service reaches the owner's database. Anything else (no row, another value, a
+// value that is no beacon, an owner with no pin) means the foreign facts would come
+// from somewhere the owner does not write, and the service refuses to decide.
+//
+// The check reads through an object the app hands in (`AccessBeaconReader`): the
+// engine and the generated client have no database connection of their own and
+// name no ORM. This module imports nothing and reaches no runtime API but WebCrypto's
+// digest, so `avaccess generate` copies it into a generated client as it is.
+/** The format marker of every beacon pins file. */
+export const BEACON_PINS_FORMAT = "aventara-access/beacons@1";
+/**
+ * The error a generated client throws when its beacons have not passed, shaped as
+ * `AccessError` is (`name`, `code`, a message that starts `Aventara Access:`): the
+ * client imports nothing, so it cannot throw the class itself.
+ */
+export const beaconMismatch = (message) => Object.assign(new Error(`Aventara Access: ${message}`), {
+    name: "AccessError",
+    code: "ACCESS_BEACON_MISMATCH",
+});
+/** A beacon: `avb_` and 32 random bytes in base64url. */
+export const BEACON = /^avb_[A-Za-z0-9_-]{43}$/;
+/** A pinned beacon hash: `sha256:` and 64 lowercase hex digits. */
+export const BEACON_HASH = /^sha256:[0-9a-f]{64}$/;
+/** A namespace or environment name: a lowercase letter, then lowercase letters, digits, `_` or `-`. */
+const NAME = /^[a-z][a-z0-9_-]{0,62}$/;
+const PIN_MEMBERS = ["format", "namespace", "environment", "beacons"];
+/**
+ * A beacon's hash, as the registry and the pins name it: `sha256:<hex>` of
+ * `<namespace>:<value>`. The namespace is bound in: a value registered under one
+ * namespace never matches, or collides with, another namespace's beacon.
+ */
+export const beaconHashOf = async (namespace, value) => {
+    const runtime = globalThis;
+    const digest = await runtime.crypto.subtle.digest("SHA-256", new runtime.TextEncoder().encode(`${namespace}:${value}`));
+    let hex = "";
+    for (const byte of new Uint8Array(digest)) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    return `sha256:${hex}`;
+};
+/**
+ * What is wrong with `pins` as `namespace`'s beacon pins of `environment` for the
+ * `owners` its rules read as foreign: its format and members, its namespace, its
+ * environment, a `sha256:` hash for every owner; `undefined` when nothing is.
+ */
+export const beaconPinsProblem = (namespace, owners, pins, environment) => {
+    if (typeof environment !== "string" || !NAME.test(environment)) {
+        return `the environment the service runs in is ${JSON.stringify(environment) ?? "missing"}, which is not an environment name (a lowercase letter, then lowercase letters, digits, "_" or "-"): name it, such as "production", and hand in that environment's pins`;
+    }
+    const file = pins;
+    if (typeof file !== "object" || file === null || Array.isArray(file)) {
+        return "the beacon pins are an object, as `avaccess pull --env <environment>` writes avAccess.beacons.<environment>.json";
+    }
+    if (file.format !== BEACON_PINS_FORMAT) {
+        return `the beacon pins' format is "${BEACON_PINS_FORMAT}"; it was ${JSON.stringify(file.format) ?? "missing"}`;
+    }
+    const unknown = Object.keys(file).filter((member) => !PIN_MEMBERS.includes(member));
+    if (unknown.length > 0) {
+        return `the beacon pins have \`format\`, \`namespace\`, \`environment\` and \`beacons\`; they do not take ${unknown.map((member) => `\`${member}\``).join(", ")}`;
+    }
+    if (file.namespace !== namespace) {
+        return `the beacon pins are namespace ${JSON.stringify(file.namespace)}'s, and the rules are namespace "${namespace}"'s: pull this project's own pins with \`avaccess pull --env <environment>\``;
+    }
+    if (file.environment !== environment) {
+        return `the beacon pins are environment ${JSON.stringify(file.environment)}'s, and the service runs in environment "${environment}": hand in avAccess.beacons.${environment}.json`;
+    }
+    const beacons = file.beacons;
+    if (typeof beacons !== "object" ||
+        beacons === null ||
+        Array.isArray(beacons) ||
+        Object.entries(beacons).some(([owner, hash]) => !NAME.test(owner) ||
+            owner === namespace ||
+            typeof hash !== "string" ||
+            !BEACON_HASH.test(hash))) {
+        return "the beacon pins' `beacons` maps each other namespace whose Resources the rules read to its beacon's `sha256:` hash";
+    }
+    const missing = owners.filter((owner) => !Object.hasOwn(beacons, owner));
+    if (missing.length > 0) {
+        return `the rules read ${missing.map((owner) => `namespace "${owner}"'s`).join(" and ")} Resources as foreign, and the beacon pins of environment "${file.environment}" hold no beacon of ${missing.length === 1 ? "it" : "them"}: pull again with \`avaccess pull --env ${file.environment} --beacon <module>\``;
+    }
+    return undefined;
+};
+/**
+ * What is wrong with the beacons of `owners` (the namespaces `namespace`'s rules
+ * read as foreign), held to `pins` (which must be `environment`'s) and read through
+ * `reader`; `undefined` when every
+ * owner's row is there and hashes to its pin. Each owner is read once, in order.
+ */
+export const beaconProblem = async (namespace, owners, pins, environment, reader) => {
+    const invalid = beaconPinsProblem(namespace, owners, pins, environment);
+    if (invalid !== undefined) {
+        return invalid;
+    }
+    if (typeof reader !== "object" ||
+        reader === null ||
+        typeof reader.read !== "function") {
+        return "the beacon reader is `{ read(namespace) }`, which reads a namespace's row in _aventara_beacon through this service's own connection";
+    }
+    const { beacons } = pins;
+    for (const owner of [...owners].sort()) {
+        let value;
+        try {
+            value = await reader.read(owner);
+        }
+        catch (error) {
+            return `reading namespace "${owner}"'s row in _aventara_beacon failed (${String(error?.message ?? error)}): this service cannot show it reaches "${owner}"'s database`;
+        }
+        if (value === null || value === undefined) {
+            return `this service's connection reads no row of namespace "${owner}" in _aventara_beacon, so it does not reach "${owner}"'s database: the rules read "${owner}"'s Resources as foreign, which works only within one database. Point the service at that database, or carry the fact in a JWT claim instead`;
+        }
+        if (typeof value !== "string" || !BEACON.test(value)) {
+            return `namespace "${owner}"'s row in _aventara_beacon holds no beacon (avb_ and 43 base64url characters): it was changed outside the service that writes it`;
+        }
+        if ((await beaconHashOf(owner, value)) !== beacons[owner]) {
+            return `namespace "${owner}"'s beacon, as this service's connection reads it, is not the one the beacon pins of environment "${environment}" hold: the service reaches another database than "${owner}"'s in that environment. Check that the pins are this environment's, pull them again with \`avaccess pull --env ${environment} --beacon <module>\` (it refuses while the databases differ), or carry the fact in a JWT claim instead`;
+        }
+    }
+    return undefined;
+};

package/dist/beacon/beacon.schema.d.ts

@@ -0,0 +1,41 @@
+import type { AccessBeaconStore } from "./beacon.store.js";
+/** The beacon table, in Better Auth's plugin schema form. */
+export declare const beaconSchema: {
+    readonly aventaraBeacon: {
+        readonly fields: {
+            readonly namespace: {
+                readonly type: "string";
+                readonly required: true;
+                readonly unique: true;
+            };
+            readonly value: {
+                readonly type: "string";
+                readonly required: true;
+            };
+            readonly createdAt: {
+                readonly type: "date";
+                readonly required: true;
+                readonly input: false;
+                readonly defaultValue: () => Date;
+            };
+        };
+    };
+};
+/** The part of Better Auth's adapter the beacon store uses. */
+export type BeaconAdapter = {
+    findOne<T>(input: {
+        model: string;
+        where: {
+            field: string;
+            value: string;
+        }[];
+    }): Promise<T | null>;
+    create<T>(input: {
+        model: string;
+        data: {
+            readonly [field: string]: unknown;
+        };
+    }): Promise<T>;
+};
+/** The beacon store over the adapter `adapterOf` resolves (Better Auth's, once built). */
+export declare const adapterBeaconStore: (adapterOf: () => Promise<BeaconAdapter>) => AccessBeaconStore;

package/dist/beacon/beacon.schema.js

@@ -0,0 +1,48 @@
+// The Access server's own beacon table, declared through Better Auth's plugin schema:
+// when the registry is on and the instance's rules name a namespace (the Access
+// server is then one of the org's namespaces, its Resources Better Auth's tables),
+// the Access plugin carries it, so Better Auth's own migration (or its CLI's
+// `generate`) creates it beside Better Auth's tables, and `access.beacon` reads and
+// writes its row through whatever adapter the app gave Better Auth.
+//
+// Its name follows Access's other tables (`accessAudit`, `accessKey`): the camelCase
+// model `aventaraBeacon`, which Better Auth's Prisma generator writes as
+// `model AventaraBeacon { … @@map("aventaraBeacon") }`. A service's own table may be
+// called `_aventara_beacon`; Better Auth's generator would write that name as the
+// Prisma model's own (`model _aventara_beacon`), which Prisma refuses, so the Access
+// server's is not. The generated client's `prismaBeacon` reads either through the
+// `AventaraBeacon` model's delegate. The auth-tables guard keeps the table closed and
+// its `value` sealed.
+/** The beacon table's Better Auth model name. */
+const BEACON_MODEL = "aventaraBeacon";
+/** The beacon table, in Better Auth's plugin schema form. */
+export const beaconSchema = {
+    [BEACON_MODEL]: {
+        fields: {
+            namespace: { type: "string", required: true, unique: true },
+            value: { type: "string", required: true },
+            createdAt: {
+                type: "date",
+                required: true,
+                input: false,
+                defaultValue: () => new Date(),
+            },
+        },
+    },
+};
+/** The beacon store over the adapter `adapterOf` resolves (Better Auth's, once built). */
+export const adapterBeaconStore = (adapterOf) => ({
+    read: async (namespace) => {
+        const row = await (await adapterOf()).findOne({
+            model: BEACON_MODEL,
+            where: [{ field: "namespace", value: namespace }],
+        });
+        return typeof row?.value === "string" ? row.value : null;
+    },
+    create: async (namespace, value) => {
+        await (await adapterOf()).create({
+            model: BEACON_MODEL,
+            data: { namespace, value },
+        });
+    },
+});

package/dist/beacon/beacon.store.d.ts

@@ -0,0 +1,29 @@
+import type { AccessBeaconReader } from "./beacon.check.js";
+/** The beacon table's name. */
+export declare const BEACON_TABLE = "_aventara_beacon";
+/** Reads and writes beacon rows, through the service's own data layer. */
+export type AccessBeaconStore = AccessBeaconReader & {
+    /**
+     * Writes `namespace`'s row with `value`, once: when the namespace has a row
+     * already, it throws (a unique `namespace`), and the row stays as it was.
+     */
+    create(namespace: string, value: string): Promise<void>;
+};
+/** A new beacon: 256 random bits from the runtime's CSPRNG, written `avb_…`. */
+export declare const newBeacon: () => string;
+/** Whether `value` is a beacon. */
+export declare const isBeacon: (value: unknown) => value is string;
+/**
+ * The namespace's own beacon, for its push: a new row written now when the
+ * namespace has none, or the row it has when its hash is the one the registry holds
+ * for the namespace (`registered`, `null` when it holds none). A row this service
+ * did not write and the registry does not know is never adopted: another service
+ * with write access to the table (a co-tenant of a shared schema) could have planted
+ * it, so it is refused (`ACCESS_BEACON_MISMATCH`) until an operator verifies it or
+ * deletes it, and the next push writes a new one. A row whose value is no beacon is
+ * refused too, never overwritten.
+ */
+export declare const ensureBeacon: (store: AccessBeaconStore, namespace: string, registered: string | null) => Promise<{
+    readonly value: string;
+    readonly created: boolean;
+}>;

package/dist/beacon/beacon.store.js

@@ -0,0 +1,78 @@
+// A service's own beacon: one row in `_aventara_beacon` with a random value, written
+// once by the service through its own data layer and never changed. The row is
+// keyed by the namespace, so a table holds one row per namespace: in a deployment
+// with a database schema per service each schema's table holds its own service's
+// row, and in one with a single schema (or a database with none) one table holds
+// every namespace's. `avaccess push --beacon <module>` writes the row the first time
+// and sends its value with the file; the registry keeps only its hash, bound to the
+// namespace.
+//
+// In a shared schema every service with write access to the table is a co-tenant
+// of every row: one that overwrites or deletes another namespace's row cannot make
+// a reader pass (the registry holds the owner's hash, bound to the owner), but it
+// makes the readers refuse at startup until the owner's service writes and pushes
+// its beacon again. The check fails closed; give each service's database role write
+// access to its own row only where the database can.
+//
+// Access writes no SQL and names no ORM: the app hands in an `AccessBeaconStore`
+// over its own data layer (the generated client's `prismaBeacon` builds one over a
+// Prisma client).
+import { AccessError } from "../access/access.error.js";
+import { randomSecret } from "../random-secret.generator.js";
+import { BEACON, beaconHashOf } from "./beacon.check.js";
+/** The beacon table's name. */
+export const BEACON_TABLE = "_aventara_beacon";
+/** A new beacon: 256 random bits from the runtime's CSPRNG, written `avb_…`. */
+export const newBeacon = () => randomSecret("avb_");
+/** Whether `value` is a beacon. */
+export const isBeacon = (value) => typeof value === "string" && BEACON.test(value);
+/**
+ * The namespace's own beacon, for its push: a new row written now when the
+ * namespace has none, or the row it has when its hash is the one the registry holds
+ * for the namespace (`registered`, `null` when it holds none). A row this service
+ * did not write and the registry does not know is never adopted: another service
+ * with write access to the table (a co-tenant of a shared schema) could have planted
+ * it, so it is refused (`ACCESS_BEACON_MISMATCH`) until an operator verifies it or
+ * deletes it, and the next push writes a new one. A row whose value is no beacon is
+ * refused too, never overwritten.
+ */
+export const ensureBeacon = async (store, namespace, registered) => {
+    const found = await store.read(namespace);
+    if (found !== null) {
+        return { value: await known(found, namespace, registered), created: false };
+    }
+    const value = newBeacon();
+    try {
+        await store.create(namespace, value);
+    }
+    catch (error) {
+        // Another write took the namespace's row first: it is held to the registry as
+        // any row found is. Anything else is the store's own failure, reported as it was.
+        const written = await store.read(namespace);
+        if (written === null) {
+            throw error;
+        }
+        return {
+            value: await known(written, namespace, registered),
+            created: false,
+        };
+    }
+    const written = await store.read(namespace);
+    if (written !== value) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `the beacon store wrote namespace "${namespace}"'s row in ${BEACON_TABLE}, and reading it back found ${written === null ? "none" : "another value"}: check that the store's read and create use the same table`);
+    }
+    return { value, created: true };
+};
+/** A row found for the namespace, taken only when the registry holds its hash. */
+const known = async (value, namespace, registered) => {
+    if (!isBeacon(value)) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `namespace "${namespace}"'s row in ${BEACON_TABLE} holds no beacon (avb_ and 43 base64url characters): it was changed outside Access. Delete the row; the next push writes a new one`);
+    }
+    if (registered === null) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `namespace "${namespace}"'s row in ${BEACON_TABLE} is there, and the registry holds no beacon of "${namespace}": this push did not write the row, and another service with write access to the table may have. An operator verifies that "${namespace}"'s own service wrote it, or deletes it; the next push then writes a new one`);
+    }
+    if ((await beaconHashOf(namespace, value)) !== registered) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `namespace "${namespace}"'s row in ${BEACON_TABLE} is not the beacon the registry holds for "${namespace}": it was changed outside "${namespace}"'s service, or this database's row is an old one. An operator verifies it or deletes it; the next push then writes a new one`);
+    }
+    return value;
+};

package/dist/better-auth/access.client-plugin.d.ts

@@ -0,0 +1,75 @@
+import type { AventaraAccessPlugin } from "./access.plugin.js";
+/** One question to the policy: may the signed-in user run `action` on `resource`, or on the one row `where` names. */
+export type AccessQuestion<R extends string = string> = {
+    readonly resource: R;
+    readonly action: "read" | "create" | "update" | "delete";
+    /** One row, by its unique where (`{ id: "c1" }`). Omitted: may the user run `action` on `resource` at all. */
+    readonly where?: {
+        readonly [field: string]: unknown;
+    };
+};
+/** `aventaraAccessClient()`'s options. */
+export type AventaraAccessClientOptions = {
+    /**
+     * The framework's API path or URL (its `api` option), where `_access/can` is
+     * served: `"/api"`, or `"https://api.example.com/api"`. A path is read against the
+     * auth client's `baseURL`, else the page's address.
+     */
+    readonly api: string;
+    /**
+     * The ClientContract's hash the questions are asked under (the generated client's).
+     * Without it, the client reads it from `GET {api}/_contract` once, and again when
+     * the framework answers that it changed.
+     */
+    readonly contractHash?: string;
+};
+/** Why `can` has no answers: the framework's (or the network's) refusal, as Better Auth's client reports one. */
+export type AccessCanError = {
+    readonly status: number;
+    readonly statusText: string;
+    /** The framework's code (`A2005`: the client is stale), when it answered with one. */
+    readonly code?: string;
+    readonly message?: string;
+};
+/** `authClient.access.can`'s answer: one boolean per question, in order, or the error. */
+export type AccessCanResult = {
+    readonly data: readonly boolean[];
+    readonly error: null;
+} | {
+    readonly data: null;
+    readonly error: AccessCanError;
+};
+/** Better Auth's client fetch, as the plugin calls it. */
+type ClientFetch = (url: string, options?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: {
+        readonly [name: string]: string;
+    };
+}) => Promise<{
+    readonly data: unknown;
+    readonly error: unknown;
+}>;
+/** What `aventaraAccessClient()` returns: a Better Auth client plugin. */
+export type AventaraAccessClientPlugin = {
+    readonly id: "aventara-access";
+    /** Types only: the server plugin, whose `jwt()` routes the client infers (`authClient.token()`). */
+    readonly $InferServerPlugin: AventaraAccessPlugin;
+    readonly pathMethods: {
+        readonly "/jwks": "GET";
+    };
+    readonly getActions: ($fetch: ClientFetch, $store: unknown, options: {
+        readonly baseURL?: string | undefined;
+    } | undefined) => {
+        readonly access: {
+            /** Asks the framework, in one request, whether the signed-in user may run each question. */
+            can(questions: readonly AccessQuestion[]): Promise<AccessCanResult>;
+        };
+    };
+};
+/**
+ * The client plugin: `createAuthClient({ plugins: [aventaraAccessClient({ api: "/api" })] })`
+ * gives `authClient.access.can([{ resource, action, where? }, ...])`.
+ */
+export declare const aventaraAccessClient: (options: AventaraAccessClientOptions) => AventaraAccessClientPlugin;
+export {};