@aventara/access 0.0.0-stage → 1.0.0-rc.1

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

@@ -0,0 +1,420 @@
+// The checks Access holds Better Auth's options to, whichever way Access is in:
+// `createAccess` runs them on its `betterAuth` block when it is built, and the
+// `aventaraAccess()` plugin on the options Better Auth hands its `init` (and
+// `accessOf(auth)` on `auth.options`, so a framework's construction refuses the same
+// configuration before the first request). One module, so the two ways in cannot
+// drift apart.
+import { ME_PATH } from "../client/access-verbs.schema.js";
+import { KIOSK_ENDPOINT_KEYS, KIOSK_PREFIX, } from "../kiosk/kiosk-verbs.schema.js";
+import { isIpv4Literal, isRangeEdge, lanRangeOf, writtenHost, } from "../kiosk/lan-range.policy.js";
+import { isRecord } from "../policies.compiler.js";
+import { REGISTRY_ENDPOINT_NAMES, REGISTRY_ROUTE_PATHS, REGISTRY_ROUTES, } from "../registry/registry.endpoints.js";
+import { AccessError } from "./access.error.js";
+/** The id of the Access plugin: `aventaraAccess()`, or the one `createAccess` installs. */
+export const ACCESS_PLUGIN_ID = "aventara-access";
+/** The id of Better Auth's `jwt()` plugin. */
+export const JWT_PLUGIN_ID = "jwt";
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+/**
+ * The endpoints of `jwt()`, which Access installs (beside the Access plugin under
+ * `createAccess`, inside it as `aventaraAccess()`): by name in Better Auth's API,
+ * and by path. A plugin of the app's that defines one would answer for it: hand out
+ * other keys, or tokens Access did not issue.
+ */
+const JWT_ENDPOINTS = new Set([
+    "getJwks",
+    "getToken",
+    "signJWT",
+    "verifyJWT",
+]);
+const JWT_PATHS = new Set(["/jwks", "/token"]);
+/**
+ * The Access plugin's own `me` route, by name and path, which `createAccess` serves:
+ * a plugin of the app's that defines it would answer `$access.me()` with another
+ * identity.
+ */
+const ACCESS_ENDPOINTS = new Set(["accessMe"]);
+const ACCESS_PATHS = new Set([ME_PATH]);
+/**
+ * The registry's routes, by name and by path (everything under `/access/v1`): a
+ * plugin of the app's that defines one would answer a service's push or pull, and
+ * read the key it sends.
+ */
+const REGISTRY_ENDPOINTS = new Set(REGISTRY_ENDPOINT_NAMES);
+const isRegistryPath = (path) => path === REGISTRY_ROUTES || path.startsWith(`${REGISTRY_ROUTES}/`);
+/**
+ * A route path as Better Auth's router reads it: one leading slash and no trailing
+ * one (`access/v1/key` is served at `/access/v1/key`). Every path is checked in this
+ * form, so no spelling of a route slips past the checks.
+ */
+const routePath = (path) => `/${path.replace(/^\/+|\/+$/g, "")}`;
+const REGISTRY_SEGMENTS = REGISTRY_ROUTES.split("/").filter((segment) => segment !== "");
+/**
+ * Whether a middleware's path pattern can match a registry route: `**` matches the
+ * rest, a `*` or `:param` segment matches any one segment (any segment with a `*` is
+ * taken as one), and a pattern that reaches past `/access/v1` matches inside it.
+ */
+const reachesRegistry = (pattern) => {
+    const segments = routePath(pattern)
+        .split("/")
+        .filter((segment) => segment !== "");
+    for (const [index, segment] of segments.entries()) {
+        if (segment.startsWith("**") || index >= REGISTRY_SEGMENTS.length) {
+            return true;
+        }
+        const any = segment.includes("*") || segment.startsWith(":");
+        if (!any && segment !== REGISTRY_SEGMENTS[index]) {
+            return false;
+        }
+    }
+    return segments.length >= REGISTRY_SEGMENTS.length;
+};
+/** Whether a route segment matches any one segment: a `:param`, or one with a `*`. */
+const anySegment = (segment) => segment.startsWith(":") || segment.includes("*");
+/**
+ * Whether an endpoint's path pattern can match a request one of the registry's
+ * routes also matches: segment by segment, a `:param` or `*` (on either side)
+ * matches any segment, `**` the rest, anything else itself (in any case). A route
+ * with parameters where the registry's has static segments (`/:a/v1/key`) is
+ * refused, not left to the router's static-first order.
+ */
+const overlapsRegistry = (pattern) => {
+    const segments = routePath(pattern)
+        .split("/")
+        .filter((segment) => segment !== "");
+    return REGISTRY_ROUTE_PATHS.some((registryPath) => {
+        const route = registryPath.split("/").filter((segment) => segment !== "");
+        for (let index = 0; index < segments.length; index += 1) {
+            const segment = segments[index];
+            if (segment.startsWith("**")) {
+                return true;
+            }
+            const other = route[index];
+            if (other === undefined) {
+                return false;
+            }
+            if (!anySegment(segment) &&
+                !anySegment(other) &&
+                segment.toLowerCase() !== other.toLowerCase()) {
+                return false;
+            }
+        }
+        return segments.length === route.length;
+    });
+};
+/** A plugin id as Better Auth's checks could take it: no case, no surrounding space. */
+export const normalisedId = (id) => typeof id === "string" ? id.trim().toLowerCase() : undefined;
+/**
+ * The plugins of a Better Auth configuration, refusing one the installer puts in
+ * itself (under any case or spacing of its id) and one that defines `jwt()`'s
+ * endpoints. `ACCESS_PLUGIN_DUPLICATE`, with a sentence naming the plugin.
+ */
+export const refuseInstalledPlugins = (plugins, installer) => {
+    const list = plugins ?? [];
+    if (!Array.isArray(list)) {
+        return refuse(`\`${installer.at}\` is an array of Better Auth plugins.`);
+    }
+    for (const plugin of list) {
+        if (plugin === installer.own) {
+            continue;
+        }
+        const id = plugin?.id;
+        const installed = normalisedId(id);
+        if (installed !== undefined &&
+            Object.hasOwn(installer.installs, installed)) {
+            throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `${installer.at} holds ${installer.installs[installed]} (plugin id "${String(id)}"), which ${installer.by} installs itself: remove it from ${installer.at}.`);
+        }
+        if (installer.registry === true && Array.isArray(plugin?.middlewares)) {
+            for (const middleware of plugin.middlewares) {
+                const path = middleware?.path;
+                if (typeof path === "string" && reachesRegistry(path)) {
+                    throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `${installer.at} holds plugin "${String(id)}", whose middleware at ${path} reaches the registry's routes, which ${installer.by} serves: it would answer a service's push or pull and read its key. Remove the plugin, or narrow its path.`);
+                }
+            }
+        }
+        const endpoints = plugin?.endpoints;
+        if (!isRecord(endpoints)) {
+            continue;
+        }
+        for (const [name, endpoint] of Object.entries(endpoints)) {
+            const path = endpoint?.path;
+            const at = typeof path === "string" ? routePath(path) : undefined;
+            if (installer.me === true &&
+                (ACCESS_ENDPOINTS.has(name) ||
+                    (at !== undefined && ACCESS_PATHS.has(at)))) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `${installer.at} holds plugin "${String(id)}", whose endpoint \`${name}\`${typeof path === "string" ? ` (${path})` : ""} is Access's own \`me\` route: it would answer \`$access.me()\` with another identity. Remove the plugin, or rename its endpoint.`);
+            }
+            if (installer.kiosk === true &&
+                (KIOSK_ENDPOINT_KEYS.has(name) ||
+                    (at !== undefined && `${at}/`.startsWith(KIOSK_PREFIX)))) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `${installer.at} holds plugin "${String(id)}", whose endpoint \`${name}\`${typeof path === "string" ? ` (${path})` : ""} is one of the kiosk profile's routes: it would answer for a PIN switch or a device. Remove the plugin, or rename its endpoint.`);
+            }
+            if (installer.registry === true &&
+                (REGISTRY_ENDPOINTS.has(name) ||
+                    (at !== undefined && (isRegistryPath(at) || overlapsRegistry(at))))) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `${installer.at} holds plugin "${String(id)}", whose endpoint \`${name}\`${typeof path === "string" ? ` (${path})` : ""} is one of the registry's routes, which ${installer.by} serves: it would answer a service's push or pull and read its key. Remove the plugin, or rename its endpoint.`);
+            }
+            if (JWT_ENDPOINTS.has(name) || (at !== undefined && JWT_PATHS.has(at))) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `${installer.at} holds plugin "${String(id)}", whose endpoint \`${name}\`${typeof path === "string" ? ` (${path})` : ""} is one of jwt()'s, which ${installer.by} installs: it would answer for Access's key set or tokens. Remove the plugin, or rename its endpoint.`);
+            }
+        }
+    }
+    return list;
+};
+/**
+ * The issuer and audience of every token: the origin of Better Auth's base URL,
+ * fixed when Access starts, as Better Auth resolves it (`baseURL`, else its
+ * environment variables, `BETTER_AUTH_URL` first), or a dynamic `baseURL`'s
+ * `fallback`. Better Auth's own default follows the request's host when the base URL
+ * is dynamic or unset; a fixed one keeps a token from one host or app from passing
+ * as another's.
+ */
+export const issuerOf = (block, modules, baseURLAt) => new URL(baseURLOf(block, modules, baseURLAt)).origin;
+/** Better Auth's base URL as {@link issuerOf} resolves it, as it was written (before the URL parser reads it). */
+export const baseURLOf = (block, modules, baseURLAt) => {
+    const { baseURL, basePath } = block;
+    const path = typeof basePath === "string" ? basePath : undefined;
+    const resolved = modules.isDynamicBaseURLConfig(baseURL)
+        ? typeof baseURL.fallback === "string"
+            ? modules.getBaseURL(baseURL.fallback, path)
+            : undefined
+        : modules.getBaseURL(typeof baseURL === "string" ? baseURL : undefined, path);
+    if (resolved === undefined || resolved === "") {
+        return refuse(`Access issues its tokens with a fixed issuer and audience, the app's base URL, and Better Auth has none: set \`${baseURLAt}\` (or \`BETTER_AUTH_URL\`), or give a dynamic \`baseURL\` its \`fallback\`.`);
+    }
+    return resolved;
+};
+/** Whether `trustedOrigins` names any origin: a list with one, or a function. */
+const namesTrustedOrigins = (trusted) => typeof trusted === "function" ||
+    (Array.isArray(trusted) && trusted.some((origin) => origin));
+/**
+ * Whether the session cookie is `sameSite: "none"`: what Better Auth sets it with,
+ * `advanced.cookies.session_token.attributes` over `advanced.defaultCookieAttributes`.
+ * Refuses it when Better Auth trusts no origin: a session cookie a browser sends
+ * from any site is read only from the origins Better Auth trusts, so there must be
+ * some.
+ */
+export const crossSiteSessionCookie = (block, trustedOriginsAt) => {
+    const advanced = (block.advanced ?? {});
+    const sameSite = advanced.cookies?.session_token?.attributes?.sameSite ??
+        advanced.defaultCookieAttributes?.sameSite;
+    const crossSite = typeof sameSite === "string" && sameSite.toLowerCase() === "none";
+    if (crossSite &&
+        !namesTrustedOrigins(block.trustedOrigins) &&
+        !globalThis.process?.env?.BETTER_AUTH_TRUSTED_ORIGINS) {
+        refuse(`the session cookie is \`sameSite: "none"\`, so a browser sends it on requests from any site, and \`${trustedOriginsAt}\` names none to accept them from. Keep the default (\`"lax"\`), or list the origins your app is served from in \`trustedOrigins\`.`);
+    }
+    return crossSite;
+};
+/** Whether Better Auth's cookie cache is on: a session read from its cookie may have been revoked since. */
+export const cookieCacheOn = (block) => block.session
+    ?.cookieCache?.enabled === true;
+/**
+ * The kiosk profile's refusals of Better Auth's options, each a way around the
+ * device binding of a session:
+ *
+ * - the cookie cache: a session the device's lock ended would still be answered
+ *   from its cookie;
+ * - `secondaryStorage` without `session.storeSessionInDatabase`: a device's sessions
+ *   must be found in the database to be ended;
+ * - `bearer()`: it hands every session's token to page code (`set-auth-token`) and
+ *   reads it back from `Authorization`, where no device credential goes with it;
+ * - `multiSession()`: it keeps every session the browser signed into and switches
+ *   back to one by its token, so a cashier would restore the manager before them;
+ * - `crossSubDomainCookies` and `SameSite=None`: the device's credential and the
+ *   session would be sent to other hosts, or from other sites;
+ * - a plain http: base URL but on a loopback host, or (`profile.insecureLan`) on an
+ *   IPv4 address inside one of the till network's ranges: the device's credential
+ *   and the sessions would cross the network in the clear. On such a LAN address no
+ *   cookie may be `Secure` (or named `__Secure-` or `__Host-`): a browser drops it
+ *   over http, and the till would silently hold no session.
+ *
+ * Answers the ranges an http: base URL is served on under `profile.insecureLan`,
+ * for the startup warning; `undefined` when it is https: or loopback.
+ */
+export const refuseKioskOptions = (block, plugins, cookieCache, 
+/** The app's base URL as written (`baseURLOf`), and where the app set it. */
+written, baseURLAt, 
+/** `profile.insecureLan`, read. */
+insecureLan) => {
+    if (cookieCache) {
+        refuse("the kiosk profile ends a PIN session the moment its device locks, and Better Auth's cookie cache would keep answering it from the cookie: turn `betterAuth.session.cookieCache` off.");
+    }
+    const session = (block.session ?? {});
+    if (block.secondaryStorage !== undefined &&
+        session.storeSessionInDatabase !== true) {
+        refuse("the kiosk profile finds a device's sessions in the database to end them, and with `secondaryStorage` Better Auth keeps them out of it: set `betterAuth.session.storeSessionInDatabase: true`.");
+    }
+    for (const plugin of plugins) {
+        const id = normalisedId(plugin?.id);
+        if (id === "bearer") {
+            refuse("the kiosk profile binds every session on an enrolled device to that device, and Better Auth's `bearer()` hands a session's token to page code and takes it back from an `Authorization` header, where the device's credential does not go: remove `bearer()` from `betterAuth.plugins`, or run the bearer clients on another instance.");
+        }
+        if (id === "multi-session") {
+            refuse("the kiosk profile ends the session before a PIN switch, and Better Auth's `multiSession()` keeps it in the browser and switches back to it, so a cashier would restore the manager before them: remove `multiSession()` from `betterAuth.plugins`.");
+        }
+    }
+    const advanced = (isRecord(block.advanced) ? block.advanced : {});
+    const crossSubDomain = advanced.crossSubDomainCookies;
+    if (isRecord(crossSubDomain) && crossSubDomain.enabled === true) {
+        refuse("the kiosk profile keeps a device's credential and its sessions on the app's own host, and `betterAuth.advanced.crossSubDomainCookies` would send them to every subdomain: turn it off.");
+    }
+    const sameSiteNone = (attributes) => isRecord(attributes) &&
+        typeof attributes.sameSite === "string" &&
+        attributes.sameSite.trim().toLowerCase() === "none";
+    const cookies = isRecord(advanced.cookies) ? advanced.cookies : {};
+    const named = Object.entries(cookies).find(([, cookie]) => sameSiteNone(isRecord(cookie) ? cookie.attributes : undefined));
+    if (sameSiteNone(advanced.defaultCookieAttributes) || named !== undefined) {
+        refuse(`the kiosk profile's device credential and sessions are not sent from other sites, and \`SameSite=None\` would send them${named === undefined ? "" : ` (\`betterAuth.advanced.cookies.${named[0]}\`)`}: use \`"lax"\`, the default.`);
+    }
+    const base = new URL(written);
+    const plainBase = base.protocol !== "https:" && !isLoopback(base);
+    // A dynamic base URL is served on each allowed host, by the request's protocol
+    // unless `protocol: "https"` fixes it: its fallback alone says nothing of them.
+    const dynamic = isRecord(block.baseURL) ? block.baseURL : undefined;
+    if (dynamic !== undefined) {
+        const hosts = Array.isArray(dynamic.allowedHosts)
+            ? dynamic.allowedHosts
+            : [];
+        const plainHosts = dynamic.protocol !== "https" &&
+            hosts.some((host) => !isLoopbackPattern(host));
+        if (plainHosts || plainBase) {
+            return refuse(insecureLan !== undefined
+                ? `\`profile.insecureLan\` takes a fixed \`${baseURLAt}\`, the server's address on the till network (such as \`"http://192.168.1.10:3000"\`): a dynamic one serves plain http: on hosts this check does not read.`
+                : plainHosts
+                    ? `the kiosk profile's device credential and PIN sessions are cookies, and the dynamic \`${baseURLAt}\` serves its allowed hosts over plain http: (its \`protocol\` is ${dynamic.protocol === undefined ? "unset, which follows the request" : JSON.stringify(dynamic.protocol)}), where they would cross the network in the clear: set \`protocol: "https"\` (http: is taken only when every allowed host is a loopback host: localhost, 127.0.0.0/8 or [::1]).`
+                    : `the kiosk profile's device credential and PIN sessions are cookies, and on \`${base.origin}\` (plain http:, the dynamic \`${baseURLAt}\`'s fallback) they would cross the network in the clear: make its fallback the app's https: URL.`);
+        }
+        return undefined;
+    }
+    if (!plainBase) {
+        return undefined;
+    }
+    if (insecureLan === undefined) {
+        return refuse(`the kiosk profile's device credential and PIN sessions are cookies, and on \`${base.origin}\` (plain http:) they would cross the network in the clear: serve the app on https: and set \`${baseURLAt}\` to its https: URL (http: is taken only on a loopback host: localhost, 127.0.0.0/8 or [::1], or, for a till network of its own, on an address \`profile.insecureLan\` lists).`);
+    }
+    const listed = insecureLan.map((range) => range.cidr).join(", ");
+    if (!isIpv4Literal(base.hostname)) {
+        return refuse(`\`profile.insecureLan\` takes a plain http: base URL on an IPv4 address only, and \`${base.origin}\` names a host by name or by IPv6, which a resolver or the network could point elsewhere: set \`${baseURLAt}\` to the server's IPv4 address on the till network, inside ${listed} (such as \`http://192.168.1.10:3000\`).`);
+    }
+    // The address as the operator reads it is the one the browser uses.
+    const host = writtenHost(written);
+    if (host !== base.hostname) {
+        return refuse(`\`${baseURLAt}\` writes the server's address as \`${host ?? written}\`, which the URL parser (and a browser) reads as \`${base.hostname}\`: write it so, \`${base.origin}\`.`);
+    }
+    const range = lanRangeOf(base.hostname, insecureLan);
+    if (range === undefined) {
+        return refuse(`\`${base.origin}\` is plain http: and outside \`profile.insecureLan\` (${listed}): set \`${baseURLAt}\` to the server's address inside one of them, or list the till network's range.`);
+    }
+    if (isRangeEdge(base.hostname, range)) {
+        return refuse(`\`${base.origin}\` is the network or broadcast address of \`${range.cidr}\`, which no server has: set \`${baseURLAt}\` to the server's own address.`);
+    }
+    const secureCookie = secureCookieSetting(advanced);
+    if (secureCookie !== undefined) {
+        return refuse(`\`betterAuth.advanced.${secureCookie}\` makes a cookie \`Secure\` (or names it \`__Secure-\` or \`__Host-\`), and a browser on \`${base.origin}\` (plain http:) drops such a cookie, so the till would never hold its session or its credential: remove it under \`profile.insecureLan\`.`);
+    }
+    return insecureLan;
+};
+/** A secure-cookie prefix, which a browser takes only from an https: page (or a loopback one). */
+const SECURE_PREFIX = /^__(?:secure|host)-/i;
+/**
+ * Where Better Auth's `advanced` options make a cookie `Secure` or give it a name a
+ * browser takes only over https:, as a path under `advanced`; `undefined` when none
+ * does.
+ */
+const secureCookieSetting = (advanced) => {
+    if (advanced.useSecureCookies === true) {
+        return "useSecureCookies";
+    }
+    if (typeof advanced.cookiePrefix === "string" &&
+        SECURE_PREFIX.test(advanced.cookiePrefix)) {
+        return "cookiePrefix";
+    }
+    if (isRecord(advanced.defaultCookieAttributes) &&
+        advanced.defaultCookieAttributes.secure === true) {
+        return "defaultCookieAttributes.secure";
+    }
+    const cookies = isRecord(advanced.cookies) ? advanced.cookies : {};
+    for (const [name, cookie] of Object.entries(cookies)) {
+        if (!isRecord(cookie)) {
+            continue;
+        }
+        if (isRecord(cookie.attributes) && cookie.attributes.secure === true) {
+            return `cookies.${name}.attributes.secure`;
+        }
+        if (typeof cookie.name === "string" && SECURE_PREFIX.test(cookie.name)) {
+            return `cookies.${name}.name`;
+        }
+    }
+    return undefined;
+};
+/**
+ * Whether a dynamic base URL's allowed-host pattern (`host[:port]`, perhaps with a
+ * scheme) names a loopback host and nothing else: a wildcard never does.
+ */
+const isLoopbackPattern = (pattern) => {
+    if (typeof pattern !== "string" || /[*?]/.test(pattern)) {
+        return false;
+    }
+    try {
+        return isLoopback(new URL(`http://${pattern.replace(/^https?:\/\//i, "")}`));
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether a URL's host is a loopback address: `localhost`, 127.0.0.0/8 or `::1`. */
+const isLoopback = (url) => url.hostname === "localhost" ||
+    url.hostname === "[::1]" ||
+    /^127\.(?:\d{1,3})\.(?:\d{1,3})\.(?:\d{1,3})$/.test(url.hostname);
+/**
+ * Better Auth's Prisma adapter's naming, when `database` is that adapter: read from
+ * the adapter the factory builds (its id, and `usePlural`). Building it touches no
+ * database, and Better Auth builds its own from the factory again when it starts,
+ * with its own options, so this one leaves nothing behind.
+ */
+export const prismaAdapterOf = (database, options) => {
+    if (typeof database !== "function") {
+        return undefined;
+    }
+    const adapter = database(options);
+    return adapter?.id === "prisma"
+        ? { usePlural: adapter.options?.adapterConfig?.usePlural === true }
+        : undefined;
+};
+/** The id of Better Auth's organization plugin. */
+const ORGANIZATION_PLUGIN_ID = "organization";
+/** The organization plugin among `plugins`, with its options; `undefined` when it is not installed. */
+export const organizationPluginOf = (plugins) => {
+    for (const plugin of plugins) {
+        const { id, options } = (plugin ?? {});
+        if (normalisedId(id) === ORGANIZATION_PLUGIN_ID) {
+            return { options: isRecord(options) ? options : {} };
+        }
+    }
+    return undefined;
+};
+/**
+ * Refuses an organization plugin whose invitations a session with an unverified
+ * email may accept, when Access trusts its memberships (`reads` says how).
+ *
+ * Better Auth's advisory GHSA-fmh4-wcc4-5jm3: from better-auth 1.6.14 on, with
+ * Better Auth's own invitation ids, `acceptInvitation` takes a session whose email
+ * matches the invitation's and is not verified, unless the organization plugin sets
+ * `requireEmailVerificationOnInvitation: true`. Anyone who signs up with the invited
+ * address first and learns the invitation's id (a forwarded email, an admin screen,
+ * an invitation list) joins at the invited role. Better Auth ships no fix (the
+ * advisory lists `>= 1.6.14` with none; the GitHub advisory database's entry still
+ * says `< 1.6.11` only), so Access refuses to trust a membership the plugin let in
+ * that way. Fail closed: only `true`, given explicitly, passes.
+ */
+export const refuseUnverifiedInvitations = (plugins, reads) => {
+    const organization = organizationPluginOf(plugins);
+    if (organization === undefined ||
+        organization.options.requireEmailVerificationOnInvitation === true) {
+        return;
+    }
+    refuse(`${reads} trusts the organization plugin's memberships, and with its options a signed-up user whose email is not verified can accept an invitation sent to that address (Better Auth advisory GHSA-fmh4-wcc4-5jm3, unfixed as of better-auth 1.7.14). Pass \`organization({ requireEmailVerificationOnInvitation: true })\`.`);
+};

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

@@ -0,0 +1,67 @@
+import type { BetterAuthOptions, betterAuth } from "better-auth";
+import type { createAuthEndpoint } from "better-auth/api";
+import type { BetterAuthAPIError, BetterAuthBaseURL, BetterAuthMiddlewareFactory, BetterAuthOAuthStateReader, BetterAuthPasswords, BetterAuthSessionCookies, BetterAuthSessionReader } from "./better-auth.require.js";
+/**
+ * Better Auth's `jwt()`, as Access calls it: the options Access gives it in, the
+ * parts of the plugin Access installs out. Its own signature is generic in its
+ * options, and the types Access states name `jwt()`'s parts by its default.
+ */
+export type JwtFactory = (options: {
+    /** `true` on the kiosk profile: `/get-session` hands out no token beside the session. */
+    readonly disableSettingJwtHeader?: boolean;
+    readonly jwt: {
+        readonly issuer: string | undefined;
+        readonly audience: string | undefined;
+        readonly expirationTime: string;
+        readonly definePayload: (source: {
+            readonly user: {
+                readonly id: string;
+            };
+            readonly session: {
+                readonly [field: string]: unknown;
+            };
+        }) => Promise<unknown>;
+    };
+}) => {
+    readonly id: string;
+    readonly version: string;
+    readonly endpoints: unknown;
+    readonly hooks: unknown;
+    readonly schema: unknown;
+};
+/** What `createAccess` takes from Better Auth. */
+export type BetterAuthModules = {
+    readonly betterAuth: typeof betterAuth;
+    /** Better Auth's tables for a set of options: its own, and its plugins'. */
+    readonly getAuthTables: (options: BetterAuthOptions) => unknown;
+    /** The base URL Better Auth resolves: the one given, else its environment variables'. */
+    readonly getBaseURL: BetterAuthBaseURL;
+    readonly isDynamicBaseURLConfig: (baseURL: unknown) => boolean;
+    readonly jwt: JwtFactory;
+    readonly createAuthEndpoint: typeof createAuthEndpoint;
+    /** A hook's handler, as plugins write theirs. */
+    readonly createAuthMiddleware: BetterAuthMiddlewareFactory;
+    /** The error a hook refuses a request with. */
+    readonly APIError: BetterAuthAPIError;
+    /** What hashing passwords takes: Node.js's `node:crypto` and Better Auth's scrypt verify. */
+    readonly passwords: BetterAuthPasswords;
+    /**
+     * The origin check Better Auth's router runs before every route (the `Origin` of
+     * a request with a cookie, and its `callbackURL` and `redirectTo`, against
+     * `trustedOrigins`), as a hook's handler.
+     */
+    readonly originCheckMiddleware: unknown;
+    /** The client address Better Auth's options read from a request's headers (`advanced.ipAddress`). */
+    readonly getIP: (headers: Headers, options: unknown) => string | null;
+    /** The session an endpoint's request carries, as Better Auth's own routes read it. */
+    readonly getSessionFromCtx: BetterAuthSessionReader;
+    /** The OAuth sign-in state of the request being handled. */
+    readonly getOAuthState: BetterAuthOAuthStateReader;
+    /** Better Auth's session cookies: set one for a new session, or delete them. */
+    readonly cookies: BetterAuthSessionCookies;
+};
+/**
+ * The installed Better Auth, checked against {@link BETTER_AUTH_RANGE}. Throws
+ * `ACCESS_BETTER_AUTH_VERSION` when it is missing or of a version outside it.
+ */
+export declare const loadBetterAuth: () => BetterAuthModules;

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

@@ -0,0 +1,65 @@
+// Loads Better Auth when `createAccess` runs, and only then. `better-auth` is an
+// optional peer: the engine (`definePolicies`, `createAccessEngine`) never needs it,
+// so importing `@aventara/access` must work without it installed. The load goes
+// through the package's own `#better-auth.require` import: under the `node` condition
+// it is Node.js's `require` (`better-auth.require.node.ts`), which a bundler for
+// Node.js also reads, so a Next.js server bundle carries Better Auth; everywhere else
+// it names no Node.js API and loads nothing. The load is synchronous: it reads Better
+// Auth's ES modules into the same module map an `import` uses, so the app's
+// `import { username } from "better-auth/plugins"` and the instance built here share
+// one copy.
+//
+// Access runs on Better Auth 1.7.12 and its later 1.7 patches (`BETTER_AUTH_RANGE`).
+// Another version is refused at construction, before any request runs on it.
+import { requireBetterAuth } from "#better-auth.require";
+import { AccessError } from "./access.error.js";
+import { BETTER_AUTH_RANGE, BETTER_AUTH_RANGE_SAID, inBetterAuthRange, } from "./better-auth.range.js";
+const INSTALL = `npm install better-auth@${BETTER_AUTH_RANGE}`;
+let loaded;
+const isMissing = (error) => {
+    const { code, message } = (error ?? {});
+    return ((code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") &&
+        typeof message === "string" &&
+        /['"]better-auth(?:\/[^'"]*)?['"]/.test(message));
+};
+/**
+ * The installed Better Auth, checked against {@link BETTER_AUTH_RANGE}. Throws
+ * `ACCESS_BETTER_AUTH_VERSION` when it is missing or of a version outside it.
+ */
+export const loadBetterAuth = () => {
+    if (loaded !== undefined) {
+        return loaded;
+    }
+    const required = requireBetterAuth();
+    if (required === undefined) {
+        throw new AccessError("ACCESS_BETTER_AUTH_VERSION", "createAccess loads better-auth through Node.js's module loader, which this runtime does not provide; run it on Node.js ^22.23.4 || >=24.22.1.");
+    }
+    if ("error" in required) {
+        if (isMissing(required.error)) {
+            throw new AccessError("ACCESS_BETTER_AUTH_VERSION", `createAccess runs on better-auth ${BETTER_AUTH_RANGE}, which is not installed: ${INSTALL}`);
+        }
+        throw required.error;
+    }
+    const { core, plugin, api, cookies, passwords } = required;
+    const installed = plugin.jwt().version;
+    if (!inBetterAuthRange(installed)) {
+        throw new AccessError("ACCESS_BETTER_AUTH_VERSION", `createAccess runs on better-auth ${BETTER_AUTH_RANGE_SAID}, and this app has better-auth ${installed ?? "of an unknown version"}: ${INSTALL}`);
+    }
+    loaded = {
+        betterAuth: core.betterAuth,
+        getAuthTables: core.getAuthTables,
+        getBaseURL: core.getBaseURL,
+        isDynamicBaseURLConfig: core.isDynamicBaseURLConfig,
+        jwt: plugin.jwt,
+        createAuthEndpoint: api.createAuthEndpoint,
+        createAuthMiddleware: api.createAuthMiddleware,
+        APIError: api.APIError,
+        passwords,
+        originCheckMiddleware: api.originCheckMiddleware,
+        getIP: api.getIP,
+        getSessionFromCtx: api.getSessionFromCtx,
+        getOAuthState: api.getOAuthState,
+        cookies,
+    };
+    return loaded;
+};

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

@@ -0,0 +1,9 @@
+/** The Better Auth versions Access runs on, as npm writes the range: `~1.7.12`. */
+export declare const BETTER_AUTH_RANGE: string;
+/** {@link BETTER_AUTH_RANGE} in words, as a refusal names it: `~1.7.12 (1.7.12 or a later 1.7 patch)`. */
+export declare const BETTER_AUTH_RANGE_SAID: string;
+/**
+ * Whether `version` is in {@link BETTER_AUTH_RANGE}: a release (no prerelease or
+ * build tag) of the floor's major and minor, at the floor's patch or later.
+ */
+export declare const inBetterAuthRange: (version: unknown) => version is string;

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

@@ -0,0 +1,28 @@
+// The Better Auth versions this release of Access runs on: 1.7.12 and every later
+// 1.7 patch. A patch is no breaking change, so Access takes it as it ships; a minor
+// or a prerelease is refused. Better Auth releases `better-auth`,
+// `@better-auth/oauth-provider` and `@better-auth/cimd` together under one version,
+// so the one range holds for the three. The package's peer ranges are this range,
+// and the gates hold them to it.
+/** The oldest Better Auth Access runs on; every later patch of its minor is taken. */
+const FLOOR = { major: 1, minor: 7, patch: 12 };
+/** The Better Auth versions Access runs on, as npm writes the range: `~1.7.12`. */
+export const BETTER_AUTH_RANGE = `~${FLOOR.major}.${FLOOR.minor}.${FLOOR.patch}`;
+/** {@link BETTER_AUTH_RANGE} in words, as a refusal names it: `~1.7.12 (1.7.12 or a later 1.7 patch)`. */
+export const BETTER_AUTH_RANGE_SAID = `${BETTER_AUTH_RANGE} (${FLOOR.major}.${FLOOR.minor}.${FLOOR.patch} or a later ${FLOOR.major}.${FLOOR.minor} patch)`;
+/**
+ * Whether `version` is in {@link BETTER_AUTH_RANGE}: a release (no prerelease or
+ * build tag) of the floor's major and minor, at the floor's patch or later.
+ */
+export const inBetterAuthRange = (version) => {
+    if (typeof version !== "string") {
+        return false;
+    }
+    const parts = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(version);
+    if (parts === null) {
+        return false;
+    }
+    return (Number(parts[1]) === FLOOR.major &&
+        Number(parts[2]) === FLOOR.minor &&
+        Number(parts[3]) >= FLOOR.patch);
+};