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

package/dist/better-auth/access.client-plugin.js

@@ -0,0 +1,133 @@
+// `aventaraAccessClient()`: the client plugin of `aventaraAccess()`, for Better
+// Auth's `createAuthClient({ plugins: [...] })`. It adds `authClient.access.can`,
+// which asks the framework, not Better Auth: one `POST {api}/_access/can` for the
+// whole list of questions, answered by the same engine that decides the real calls
+// (`accessOf(auth).policy`, with the row looked up within the caller's scope), one
+// boolean per question. So the two paths have one evaluator. The answer only shapes
+// the UI: the real call is still checked.
+//
+// It sends Better Auth's own fetch, so the session cookie (or the bearer token the
+// app gives Better Auth's client) goes with it, and answers as Better Auth's client
+// actions do, `{ data, error }`. It names no Node.js API and loads nothing from
+// `better-auth` at runtime: it runs in the browser.
+/** The framework protocol version the questions are asked under. */
+const PROTOCOL_VERSION = "1";
+/** A protocol envelope's code, when a body is one. */
+const codeOf = (body) => {
+    const code = body?.code;
+    return typeof code === "string" ? code : undefined;
+};
+const failure = (status, statusText, body) => {
+    const code = codeOf(body);
+    const message = body?.message;
+    return {
+        data: null,
+        error: {
+            status,
+            statusText,
+            ...(code === undefined ? {} : { code }),
+            ...(typeof message === "string" ? { message } : {}),
+        },
+    };
+};
+/** Whether every answer is a boolean. */
+const allBooleans = (answers) => {
+    for (const answer of answers) {
+        if (typeof answer !== "boolean") {
+            return false;
+        }
+    }
+    return true;
+};
+/** A Better Auth fetch error as `can` reports it. */
+const fetchFailure = (error) => {
+    const { status, statusText } = (error ?? {});
+    return failure(typeof status === "number" ? status : 0, typeof statusText === "string" ? statusText : "", error);
+};
+/**
+ * The client plugin: `createAuthClient({ plugins: [aventaraAccessClient({ api: "/api" })] })`
+ * gives `authClient.access.can([{ resource, action, where? }, ...])`.
+ */
+export const aventaraAccessClient = (options) => {
+    const { api, contractHash: given } = options ?? {};
+    if (typeof api !== "string" || api === "") {
+        throw new TypeError('Aventara Access: aventaraAccessClient takes `{ api }`, the framework\'s API path or URL ("/api").');
+    }
+    return {
+        id: "aventara-access",
+        $InferServerPlugin: {},
+        pathMethods: { "/jwks": "GET" },
+        getActions: ($fetch, _$store, clientOptions) => {
+            const base = clientOptions?.baseURL ??
+                globalThis
+                    .location?.href;
+            /** `{api}/<route>`, absolute, so Better Auth's fetch does not read it against its own base path. */
+            const route = (path) => new URL(`${api.replace(/\/+$/, "")}/${path}`, base).href;
+            let discovered;
+            /** The ClientContract's hash: the one given, else `GET {api}/_contract`'s. */
+            const hashOf = async () => {
+                if (given !== undefined) {
+                    return given;
+                }
+                if (discovered !== undefined) {
+                    return discovered;
+                }
+                const { data, error } = await $fetch(route("_contract"), {
+                    method: "GET",
+                });
+                const hash = data?.protocol?.hash;
+                if (error !== null && error !== undefined) {
+                    return fetchFailure(error);
+                }
+                if (typeof hash !== "string") {
+                    return failure(500, "The framework's /_contract answer carries no protocol hash");
+                }
+                discovered = hash;
+                return hash;
+            };
+            const ask = async (questions, hash) => $fetch(route("_access/can"), {
+                method: "POST",
+                body: { questions },
+                headers: {
+                    "aventara-protocol-version": PROTOCOL_VERSION,
+                    "aventara-contract-hash": hash,
+                },
+            });
+            const can = async (questions) => {
+                if (questions.length === 0) {
+                    return { data: [], error: null };
+                }
+                let hash = await hashOf();
+                if (typeof hash !== "string") {
+                    return hash;
+                }
+                let answer = await ask(questions, hash);
+                // A hash read from `_contract` is stale once the framework redeploys: read it
+                // again, once.
+                if (given === undefined &&
+                    codeOf(answer.error) === "A2005" &&
+                    answer.error.status === 409) {
+                    discovered = undefined;
+                    hash = await hashOf();
+                    if (typeof hash !== "string") {
+                        return hash;
+                    }
+                    answer = await ask(questions, hash);
+                }
+                if (answer.error !== null && answer.error !== undefined) {
+                    return fetchFailure(answer.error);
+                }
+                const answers = answer.data
+                    ?.data;
+                if (codeOf(answer.data) !== "A1000" ||
+                    !Array.isArray(answers) ||
+                    answers.length !== questions.length ||
+                    !allBooleans(answers)) {
+                    return failure(500, "The framework's /_access/can answer is not one boolean per question", answer.data);
+                }
+                return { data: answers, error: null };
+            };
+            return { access: { can } };
+        },
+    };
+};

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

@@ -0,0 +1,164 @@
+import type { jwt } from "better-auth/plugins/jwt";
+import type { AccessPoliciesOptions } from "../access/access-options.js";
+import { type BetterAuthBlock } from "../access/better-auth.hardening.js";
+import { type BetterAuthModules } from "../access/better-auth.loader.js";
+import { type AccessClaimsDeclaration, type AccessClaimsOf, type AccessClaimsSource, type AccessIdentity } from "../access/claims.mapper.js";
+import { type BetterAuthTablesFacts, type CheckedPolicies } from "../access/policies-block.checker.js";
+import { type AuditLog } from "../audit/audit.log.js";
+import type { AccessAuditOptions } from "../audit/audit-event.js";
+import { type AccessMcpOptions } from "../mcp/mcp-options.js";
+import { type AccessPasswordsOptions } from "../passwords/passwords.options.js";
+import { type RegistrySettings } from "../registry/access.registry.js";
+import { type AccessRegistryOptions } from "../registry/registry.options.js";
+import { type AccessResourcesOptions, type ResourcesChoice } from "../resources/auth-tables.guard.js";
+import { type AccessOrganizationBridge, type CheckedBridge } from "./organization.bridge.js";
+type GovernedShape = {
+    readonly [resource: string]: readonly string[];
+};
+/**
+ * The principal (`me`) an instance hands the engine: the rules' principal type when
+ * the rules are the builder, else what `principal` returns (by default the identity).
+ */
+type AccessPrincipalOf<R, M> = unknown extends R ? M : R;
+/**
+ * The request's principal (`me`) from a verified identity: the app maps `sub` to its
+ * own profile, and `null` leaves the caller anonymous. With the builder as the rules,
+ * it returns their principal type.
+ */
+type AccessPrincipalFunction<C extends AccessClaimsDeclaration, R, M> = (identity: AccessIdentity<C>) => (unknown extends R ? M : NoInfer<R>) | null | Promise<(unknown extends R ? M : NoInfer<R>) | null>;
+/**
+ * The `principal` option: optional while the identity (`{ sub, claims }`) is itself
+ * the rules' principal type, and required when the rules are typed with another.
+ */
+type AccessPrincipalOption<C extends AccessClaimsDeclaration, R, M> = [
+    AccessIdentity<C>
+] extends [R] ? {
+    /** The request's principal (`me`) from the verified identity; without it, `me` is the identity, `{ sub, claims }`. */
+    readonly principal?: AccessPrincipalFunction<C, R, M>;
+} : {
+    /** The request's principal (`me`) from the verified identity, typed as the rules' principal. */
+    readonly principal: AccessPrincipalFunction<C, R, M>;
+};
+/** `aventaraAccess()`'s options. */
+export type AventaraAccessOptions<C extends AccessClaimsDeclaration, R, Gov extends GovernedShape, M, E extends boolean = false> = {
+    /** The rules and the claims they read, as `createAccess` takes them. */
+    readonly policies: AccessPoliciesOptions<C, R, Gov>;
+    /**
+     * Which Resource of the rules' schema is each of Better Auth's tables, and which
+     * of them are Resources of the rules, as `createAccess` takes it. Every other
+     * table of Better Auth's is closed, and no grant opens a secret column.
+     */
+    readonly resources?: AccessResourcesOptions;
+    /**
+     * The organization bridge: a member's role in the session's active organization
+     * (Better Auth's `organization()` plugin) fills one claim of the token, and the
+     * organization another. Each grant on the role must be held to the organization.
+     */
+    readonly organization?: AccessOrganizationBridge<C>;
+    /**
+     * The audit log, as `createAccess` takes it: `true` writes the `accessAudit` table
+     * (Better Auth's `generate`/`migrate` create it), `{ sink }` hands each event to the
+     * app instead. Off by default.
+     */
+    readonly audit?: AccessAuditOptions;
+    /**
+     * How passwords are hashed, as `createAccess` takes it: argon2id at
+     * `"owasp-minimum"` (the default) or `"rfc9106-low-memory"`, and with
+     * `legacyScrypt: true` Better Auth's scrypt hashes accepted. A hash at another
+     * profile, or scrypt, is rehashed at the profile at its account's next sign-in.
+     * An app that sets Better Auth's `emailAndPassword.password` hashes its
+     * own way, and may not set this too.
+     */
+    readonly passwords?: AccessPasswordsOptions;
+    /**
+     * The policy registry, as `createAccess` takes it: `{ enabled: true }` makes the
+     * app the hub other services push their files to and pull them from, its tables
+     * this plugin's (Better Auth's `generate`/`migrate` create them) and its routes
+     * this plugin's endpoints under `/access/v1/namespaces`; `accessOf(auth).registry`
+     * is the operator's API. Off by default: no tables, no routes.
+     */
+    readonly registry?: AccessRegistryOptions<E>;
+    /**
+     * Access as the authorization layer of an MCP endpoint, as `createAccess`
+     * takes it: `{ resource }`, the endpoint's URL. Better Auth's OAuth provider
+     * (`@better-auth/oauth-provider`) goes in `plugins` after this plugin, with the
+     * endpoint among its `resources`; `accessOf(auth).mcp` is the framework's
+     * `mcp.authorization`.
+     */
+    readonly mcp?: AccessMcpOptions;
+    /**
+     * The service's own audience, an opt-in, as `createAccess` takes it (RFC 8707): with
+     * it, `accessOf(auth).state` takes a bearer token only when it is the OAuth
+     * provider's access token addressed to this audience alone, and refuses the
+     * one-org token `GET /token` issues. Off by default.
+     */
+    readonly audience?: string;
+} & AccessPrincipalOption<C, R, M>;
+/** The `jwt()` plugin `aventaraAccess()` carries inside it. */
+type JwtPlugin = ReturnType<typeof jwt>;
+/** What `aventaraAccess()` returns: a Better Auth plugin, with `jwt()`'s endpoints, hooks and table. */
+export type AventaraAccessPlugin<C extends AccessClaimsDeclaration = AccessClaimsDeclaration, Gov extends GovernedShape = GovernedShape, M = unknown, E extends boolean = boolean, P extends boolean = boolean> = {
+    readonly id: "aventara-access";
+    readonly version: string;
+    readonly init: (context: unknown) => void;
+    readonly endpoints: JwtPlugin["endpoints"];
+    readonly hooks: JwtPlugin["hooks"];
+    readonly schema: JwtPlugin["schema"];
+    /** Types only, as Better Auth's plugins carry theirs: `typeof auth.$Infer.AccessMe` is the principal. */
+    readonly $Infer: {
+        readonly AccessMe: M;
+        readonly AccessClaims: AccessClaimsOf<C>;
+        readonly AccessGoverned: Gov;
+        /** Whether the plugin serves the registry (`registry: { enabled: true }`): `accessOf(auth).registry` is typed present exactly then. */
+        readonly AccessRegistryEnabled: E;
+        /** Whether `mcp` is given: `accessOf(auth).mcp` is there exactly then. */
+        readonly AccessMcp: P;
+    };
+};
+/** What Better Auth's options at `init` (or `auth.options`) fixed: the facts the request state and the engine read. */
+type PluginStart = {
+    readonly issuer: string;
+    readonly crossSite: boolean;
+    readonly facts: BetterAuthTablesFacts;
+    /** With `mcp`: the MCP endpoint, and the authorization server `accessOf(auth).mcp` names (the issuer). */
+    readonly mcp?: {
+        readonly resource: string;
+        readonly server: string;
+    };
+    /** With `audience`: the service's own audience. */
+    readonly audience?: string;
+    /** The provider's UserInfo URL, which a token asked with `openid` names beside its resource. */
+    readonly userInfo: string | undefined;
+};
+/** What `aventaraAccess()` was built with, for `accessOf`. */
+type PluginKernel = {
+    readonly checked: CheckedPolicies;
+    readonly resources: ResourcesChoice;
+    readonly bridge: CheckedBridge | undefined;
+    readonly modules: BetterAuthModules;
+    /** The audit log, when `audit` is on: the decisions of `accessOf(auth).policy` go to it. */
+    readonly auditLog: AuditLog | undefined;
+    /** The registry's settings when the plugin serves it, for `accessOf(auth).registry`; `undefined` when it is off. */
+    readonly registry: RegistrySettings | undefined;
+    /** Better Auth's options, checked as `init` checks them. */
+    start(options: BetterAuthBlock, own: unknown): PluginStart;
+    /** A session's claims, as its token is issued with them; `context` is Better Auth's. */
+    claimsFor(context: () => Promise<unknown>, source: AccessClaimsSource): Promise<{
+        readonly [claim: string]: string | number | boolean;
+    }>;
+};
+/**
+ * The Access plugin for Better Auth: `betterAuth({ plugins: [aventaraAccess({ policies })] })`.
+ * It carries Better Auth's `jwt()` (whose tokens carry `sub` and the declared claims,
+ * under the app's base URL as issuer and audience), so `jwt()` is not added beside
+ * it. `accessOf(auth)` is the framework's `access` option. `better-auth` is loaded
+ * here, and must be in Access's range, `~1.7.12` (1.7.12 or a later 1.7 patch).
+ */
+export declare function aventaraAccess<const C extends AccessClaimsDeclaration, R = unknown, Gov extends GovernedShape = Record<never, never>, M = AccessIdentity<C>, const E extends boolean = false, X extends AccessMcpOptions | undefined = undefined>(options: AventaraAccessOptions<C, R, Gov, M, E> & {
+    readonly mcp?: X;
+}): AventaraAccessPlugin<C, Gov, AccessPrincipalOf<R, M>, E, [
+    X
+] extends [undefined] ? false : [X] extends [AccessMcpOptions] ? true : boolean>;
+/** What `aventaraAccess()` was built with, when `plugin` is one; `undefined` for any other plugin. */
+export declare const pluginKernelOf: (plugin: unknown) => PluginKernel | undefined;
+export {};

package/dist/better-auth/access.plugin.js

@@ -0,0 +1,348 @@
+// `aventaraAccess()`: Access as a Better Auth plugin, for an app that builds Better
+// Auth itself (`betterAuth({ plugins: [aventaraAccess({ policies })] })`). It is the
+// other way in beside `createAccess`, and runs the same code: the `policies` block
+// and `principal` checked when it is called; Better Auth's options checked when
+// Better Auth initialises the plugin, as `createAccess` checks its `betterAuth` block
+// (the fixed issuer, the session cookie's site, the claims' sources, which Resource
+// is which of Better Auth's tables, no second `jwt()`); and tokens issued by Better
+// Auth's own `jwt()`, which the plugin carries inside it, with `sub` and the declared
+// claims only. `accessOf(auth)` then gives the framework its `access` option.
+//
+// Passwords are hashed with argon2id as under `createAccess` (the `passwords` block,
+// or the app's own `emailAndPassword.password`, which passes through): the plugin
+// puts the hook in Better Auth's context when Better Auth initialises it.
+//
+// The audit log is here as under `createAccess` (`audit: true` or `{ sink }`): sign-ins,
+// sign-outs, refused sign-ins and tokens from Better Auth's hooks, and the decisions
+// of `accessOf(auth).policy`.
+//
+// The registry is here too, as under `createAccess` (`registry: { enabled: true }`),
+// which makes the app the hub other services push to and pull from: its tables are
+// this plugin's schema, so Better Auth's `migrate`/`generate` create them through the
+// app's own adapter, and its routes are this plugin's endpoints, so Better Auth serves
+// them wherever the app mounts it. A service reaches them only with its namespace's
+// key; the operator's API (namespaces, keys, the org's guardrails) is
+// `accessOf(auth).registry`, in the app's own process, and no route opens it. What
+// else `createAccess` adds beside Better Auth (profiles, its `handler`, the standalone
+// host) is not here: the app owns its Better Auth instance and mounts it as it
+// already does.
+//
+// `jwt()` is carried inside this plugin, under the Access plugin's id. A Better Auth
+// plugin that looks `jwt()` up by its id (`ctx.getPlugin("jwt")`, as the OAuth
+// provider does for its issuer and keys) finds the carried one: the plugin answers
+// for that id in Better Auth's context (`getPlugin`, `hasPlugin`) when Better Auth
+// starts it, so a plugin that reads it as it starts comes after this one in
+// `plugins`.
+//
+// With `mcp` or `audience`, Access reads the tokens Better Auth's OAuth provider (in
+// `plugins` after this plugin) issues, as under `createAccess`: PKCE is required of
+// every authorization request, `accessOf(auth).mcp` is the framework's
+// `mcp.authorization`, and with `audience` the service takes only bearer tokens
+// addressed to it. Access issues no token and serves no OAuth route.
+import { AccessError } from "../access/access.error.js";
+import { ACCESS_PLUGIN_ID, cookieCacheOn, crossSiteSessionCookie, issuerOf, JWT_PLUGIN_ID, normalisedId, refuseInstalledPlugins, refuseUnverifiedInvitations, } from "../access/better-auth.hardening.js";
+import { loadBetterAuth, } from "../access/better-auth.loader.js";
+import { issuedClaims, } from "../access/claims.mapper.js";
+import { betterAuthTablesFor, checkPoliciesBlock, } from "../access/policies-block.checker.js";
+import { sessionStillLive } from "../access/request.state.js";
+import { sessionWatch } from "../access/session.hooks.js";
+import { auditDestinationOf, createAuditLog, } from "../audit/audit.log.js";
+import { auditSchema } from "../audit/audit.schema.js";
+import { authorizationServerOf, checkMcpOptions, } from "../mcp/mcp-options.js";
+import { userInfoAudience } from "../oauth/access-token.verifier.js";
+import { checkOAuthProvider, checkResourceUrl, oauthUseOf, pkceGuard, } from "../oauth/oauth-provider.hardening.js";
+import { checkPasswordsOptions, passwordHookOf, passwordRehashHook, } from "../passwords/passwords.options.js";
+import { isRecord } from "../policies.compiler.js";
+import { createRegistry, } from "../registry/access.registry.js";
+import { registryEndpoints, registryOnRequest, } from "../registry/registry.endpoints.js";
+import { registryOptionsOf, } from "../registry/registry.options.js";
+import { registrySchema } from "../registry/registry.schema.js";
+import { checkResourcesOptions, } from "../resources/auth-tables.guard.js";
+import { bridgedClaims, checkBridge, checkBridgePlugins, } from "./organization.bridge.js";
+/**
+ * What each plugin `aventaraAccess()` built was built with, by plugin: a map this
+ * module alone holds, so no object but one it returned passes for the plugin.
+ */
+const KERNELS = new WeakMap();
+const TOP_LEVEL = new Set([
+    "policies",
+    "principal",
+    "resources",
+    "organization",
+    "audit",
+    "passwords",
+    "registry",
+    "mcp",
+    "audience",
+]);
+/** The plugins `aventaraAccess()` carries itself, by id: a second one in `plugins` would answer for its routes. */
+const CARRIED = { [JWT_PLUGIN_ID]: "jwt()" };
+/**
+ * The Access plugin for Better Auth: `betterAuth({ plugins: [aventaraAccess({ policies })] })`.
+ * It carries Better Auth's `jwt()` (whose tokens carry `sub` and the declared claims,
+ * under the app's base URL as issuer and audience), so `jwt()` is not added beside
+ * it. `accessOf(auth)` is the framework's `access` option. `better-auth` is loaded
+ * here, and must be in Access's range, `~1.7.12` (1.7.12 or a later 1.7 patch).
+ */
+export function aventaraAccess(options) {
+    if (!isRecord(options)) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "aventaraAccess takes one object: `{ policies, principal?, resources?, organization?, audit?, passwords?, registry?, mcp?, audience? }`.");
+    }
+    for (const key of Object.keys(options)) {
+        if (!TOP_LEVEL.has(key)) {
+            throw new AccessError("ACCESS_OPTIONS_INVALID", `aventaraAccess does not take \`${key}\`; it takes \`policies\`, \`principal\`, \`resources\`, \`organization\`, \`audit\`, \`passwords\`, \`registry\`, \`mcp\` and \`audience\`. Better Auth's own options go to betterAuth({...}) beside it.`);
+        }
+    }
+    const given = options;
+    if (given.policies === undefined) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "the `policies` option is missing: pass `{ rules, claims }`, the rules (`definePolicies(model)…`) and the claims they read.");
+    }
+    const checked = checkPoliciesBlock(given.policies, given.principal);
+    const resources = checkResourcesOptions(given.resources);
+    const bridge = checkBridge(given.organization, checked.claims);
+    const passwords = checkPasswordsOptions(given.passwords);
+    const registrySettings = registryOptionsOf(given.registry);
+    // The block's shape now; its resource against the issuer when Better Auth starts.
+    const mcp = checkMcpOptions(given.mcp, "mcp", "");
+    const oauthOn = oauthUseOf(mcp, given.audience === undefined
+        ? undefined
+        : checkResourceUrl(given.audience, "audience", ""), undefined);
+    const modules = loadBetterAuth();
+    // The bridge owns its two claims: neither the user's field of the same name nor
+    // `claimsOf` fills them.
+    const bridged = bridge === undefined ? [] : [bridge.claim, bridge.organizationClaim];
+    const ownClaims = {
+        ...checked.claims,
+    };
+    for (const claim of bridged) {
+        delete ownClaims[claim];
+    }
+    const claimsOf = checked.claimsOf === undefined || bridge === undefined
+        ? checked.claimsOf
+        : async (source) => {
+            const answer = await checked.claimsOf(source);
+            if (!isRecord(answer)) {
+                return answer;
+            }
+            const kept = { ...answer };
+            for (const claim of bridged) {
+                delete kept[claim];
+            }
+            return kept;
+        };
+    const claimsFor = async (context, source) => {
+        const claims = await issuedClaims(source, bridge === undefined ? checked.claims : ownClaims, claimsOf);
+        if (bridge === undefined) {
+            return claims;
+        }
+        const fromBridge = await bridgedClaims(bridge, (await context()), source);
+        return fromBridge === undefined ? claims : { ...claims, ...fromBridge };
+    };
+    const start = (block, own) => {
+        const plugins = refuseInstalledPlugins(block.plugins, {
+            by: "aventaraAccess()",
+            at: "plugins",
+            installs: CARRIED,
+            own,
+            registry: registrySettings !== undefined,
+        });
+        for (const plugin of plugins) {
+            const id = plugin?.id;
+            if (plugin !== own && normalisedId(id) === ACCESS_PLUGIN_ID) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `plugins holds a second Access plugin (plugin id "${String(id)}") beside aventaraAccess(): Better Auth runs one. Remove it.`);
+            }
+        }
+        if (resources.members) {
+            refuseUnverifiedInvitations(plugins, "`resources: { members: true }`");
+        }
+        if (bridge !== undefined) {
+            checkBridgePlugins(plugins, bridge);
+        }
+        const issuer = issuerOf(block, modules, "baseURL");
+        const checkedMcp = checkMcpOptions(given.mcp, "mcp", issuer);
+        const audience = given.audience === undefined
+            ? undefined
+            : checkResourceUrl(given.audience, "audience", issuer);
+        const userInfo = userInfoAudience(block, modules);
+        const use = oauthUseOf(checkedMcp, audience, userInfo);
+        if (use !== undefined) {
+            checkOAuthProvider(plugins, use, { at: "plugins", own });
+        }
+        return {
+            ...(checkedMcp === undefined
+                ? {}
+                : {
+                    mcp: {
+                        resource: checkedMcp.resource,
+                        server: authorizationServerOf(issuer, "baseURL"),
+                    },
+                }),
+            ...(audience === undefined ? {} : { audience }),
+            userInfo,
+            issuer,
+            crossSite: crossSiteSessionCookie(block, "trustedOrigins"),
+            facts: betterAuthTablesFor({
+                options: block,
+                modules,
+                checked,
+                resources,
+                bridged,
+            }),
+        };
+    };
+    // Fixed when Better Auth initialises the plugin, from its options: the tokens'
+    // issuer and audience, and the context the claims, the session check and the
+    // audit log read. `jwt()` hands its payload function the session alone, never
+    // Better Auth's context, so these are the plugin's, not each context's: a plugin
+    // started again (Better Auth's migrations build another context from the same
+    // options) must find every one of them as it was, or it is refused.
+    let first;
+    const contextOf = async () => first?.context;
+    const auditTo = auditDestinationOf(given.audit);
+    const auditLog = auditTo === undefined
+        ? undefined
+        : createAuditLog(auditTo, async () => (await contextOf()));
+    const watch = sessionWatch({
+        kind: "web",
+        auditLog,
+        modules,
+        plugins: () => first?.plugins ?? [],
+    });
+    const carried = modules.jwt({
+        jwt: {
+            get issuer() {
+                return first?.issuer;
+            },
+            get audience() {
+                return first?.issuer;
+            },
+            expirationTime: `${checked.tokenTtl}s`,
+            definePayload: async (source) => {
+                if (first?.cookieCache === true) {
+                    await sessionStillLive(contextOf, source.session, () => new modules.APIError("UNAUTHORIZED", {
+                        message: "The session has ended.",
+                    }));
+                }
+                return claimsFor(contextOf, source);
+            },
+        },
+    });
+    // The registry's routes store through the adapter of the Better Auth that started
+    // the plugin: every instance it is in has the same database (`init` refuses one
+    // that does not), and no route runs before Better Auth has started it.
+    const registryStore = registrySettings === undefined
+        ? undefined
+        : createRegistry(async () => {
+            const context = first?.context;
+            if (context?.adapter === undefined) {
+                throw new AccessError("ACCESS_OPTIONS_INVALID", "the registry was asked before Better Auth started aventaraAccess(): build Better Auth with it in its plugins first.");
+            }
+            return context.adapter;
+        }, registrySettings);
+    const registryRoutes = registryStore === undefined
+        ? undefined
+        : registryEndpoints(registryStore, modules.createAuthEndpoint);
+    const carriedHooks = carried.hooks;
+    const plugin = {
+        id: ACCESS_PLUGIN_ID,
+        version: carried.version,
+        init(ctx) {
+            const { options: block } = ctx;
+            const started = start(block, plugin);
+            const now = {
+                issuer: started.issuer,
+                crossSite: started.crossSite,
+                cookieCache: cookieCacheOn(block),
+                database: block.database,
+                secondaryStorage: block.secondaryStorage,
+            };
+            if (first === undefined) {
+                first = {
+                    ...now,
+                    context: ctx,
+                    plugins: Array.isArray(block.plugins) ? block.plugins : [],
+                };
+            }
+            else if (now.issuer !== first.issuer ||
+                now.crossSite !== first.crossSite ||
+                now.cookieCache !== first.cookieCache ||
+                now.database !== first.database ||
+                now.secondaryStorage !== first.secondaryStorage) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", "one aventaraAccess() plugin is in two Better Auth instances whose options differ (database, secondary storage, base URL, session cookie or cookie cache): call aventaraAccess() for each betterAuth({...}).");
+            }
+            // Better Auth's password hook, argon2id unless the app set its own: put in
+            // Better Auth's context, which Better Auth built from its options before
+            // initialising its plugins.
+            const hook = passwordHookOf(passwords, block.emailAndPassword, modules, contextOf, "emailAndPassword");
+            const watched = watch.init?.();
+            // The carried `jwt()`, found by its own id in Better Auth's context, as a plugin
+            // beside it would be: the OAuth provider reads its issuer and keys there.
+            const { getPlugin, hasPlugin } = ctx;
+            const jwtLookup = {
+                getPlugin: (id) => id === JWT_PLUGIN_ID ? carried : getPlugin(id),
+                hasPlugin: (id) => id === JWT_PLUGIN_ID || hasPlugin(id),
+            };
+            const { password } = ctx;
+            return {
+                ...watched,
+                context: {
+                    ...watched?.context,
+                    ...jwtLookup,
+                    ...(hook === undefined
+                        ? {}
+                        : {
+                            password: {
+                                ...password,
+                                hash: hook.hash,
+                                verify: hook.verify,
+                            },
+                        }),
+                },
+            };
+        },
+        endpoints: registryRoutes === undefined
+            ? carried.endpoints
+            : { ...carried.endpoints, ...registryRoutes },
+        // A push's key is checked before Better Auth reads its body, on any mount.
+        ...(registryStore === undefined
+            ? {}
+            : { onRequest: registryOnRequest(registryStore) }),
+        hooks: {
+            before: [
+                ...(carriedHooks.before ?? []),
+                ...(oauthOn === undefined ? [] : [pkceGuard(modules)]),
+                ...(watch.hooks?.before ?? []),
+            ],
+            after: [
+                ...(carriedHooks.after ?? []),
+                ...(watch.hooks?.after ?? []),
+                // Inert unless Better Auth's password hook is Access's (the app's own passes through).
+                passwordRehashHook(modules),
+            ],
+        },
+        schema: {
+            ...carried.schema,
+            ...(registrySettings === undefined ? {} : registrySchema),
+            ...(auditTo?.kind === "table" ? auditSchema : {}),
+        },
+        $Infer: {},
+    };
+    const kernel = {
+        checked,
+        resources,
+        bridge,
+        modules,
+        auditLog,
+        registry: registrySettings,
+        start,
+        claimsFor,
+    };
+    KERNELS.set(plugin, kernel);
+    // The declared return type states it; a cast restating it costs the type-checker
+    // the whole plugin type again.
+    return plugin;
+}
+/** What `aventaraAccess()` was built with, when `plugin` is one; `undefined` for any other plugin. */
+export const pluginKernelOf = (plugin) => typeof plugin === "object" && plugin !== null
+    ? KERNELS.get(plugin)
+    : undefined;