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

package/dist/mcp/mcp-options.js

@@ -0,0 +1,72 @@
+// The `mcp` block: Access as the authorization layer of one MCP endpoint
+// (`createAccess({ mcp: { resource } })`, `aventaraAccess({ mcp: { resource } })`).
+// Better Auth authenticates: its own OAuth provider (`@better-auth/oauth-provider`,
+// which the app installs in Better Auth's plugins as it would for plain Better Auth,
+// its options passed through untouched) is the authorization server and issues the
+// tokens. Access issues none: it names the MCP endpoint they are for, refuses a
+// provider configured short of what an agent's authorization needs
+// (`oauth/oauth-provider.hardening.ts`), verifies the tokens, maps their scopes to the
+// rules under the `agent` origin, and gives the framework `mcp.authorization`:
+// `access.mcp`, `{ servers, verify }`.
+//
+// The authorization server's issuer is Access's fixed issuer, the origin of Better
+// Auth's base URL, which `jwt()` signs every token with:
+// one string, which the provider's metadata, its `iss` in each authorization
+// response (RFC 9207) and the tokens' `iss` all carry, and which the endpoint's
+// protected-resource metadata advertises. It is https, or, for a server on this
+// machine, `http://127.0.0.1` or `http://[::1]` (the framework's rule for MCP authorization servers): a name
+// such as `localhost` is resolved, and may resolve elsewhere.
+import { AccessError } from "../access/access.error.js";
+import { checkResourceUrl } from "../oauth/oauth-provider.hardening.js";
+import { isRecord } from "../policies.compiler.js";
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+/** The hosts an http authorization server may name, as the WHATWG URL parser writes them (the framework's rule). */
+const LOOPBACK_SERVER_HOSTS = new Set([
+    "127.0.0.1",
+    "[::1]",
+]);
+/**
+ * The `mcp` block, checked: `{ resource, openRegistration? }`, the MCP endpoint's URL
+ * as its protected-resource metadata writes it (`checkResourceUrl`), and whether open
+ * registration is taken. `undefined` when the block is absent.
+ */
+export const checkMcpOptions = (value, at, issuer) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value) ||
+        Object.keys(value).some((key) => key !== "resource" && key !== "openRegistration") ||
+        typeof value.resource !== "string" ||
+        (value.openRegistration !== undefined &&
+            typeof value.openRegistration !== "boolean")) {
+        return refuse(`\`${at}\` is \`{ resource, openRegistration? }\`: the MCP endpoint's URL, as its protected-resource metadata names it (\`"https://app.example.com/mcp"\`), and \`true\` to take the OAuth provider's open client registration.`);
+    }
+    return {
+        resource: checkResourceUrl(value.resource, `${at}.resource`, issuer),
+        openRegistration: value.openRegistration === true,
+    };
+};
+/**
+ * The authorization server `access.mcp.servers` names: the issuer, when it is https,
+ * or http on `127.0.0.1` or `[::1]` (the framework's rule). `localhost` is
+ * refused with the address to write instead.
+ */
+export const authorizationServerOf = (issuer, baseURLAt) => {
+    const url = new URL(issuer);
+    if (url.port === "0") {
+        return refuse(`\`mcp\` advertises Access's issuer (${issuer}, from \`${baseURLAt}\`) as the MCP endpoint's OAuth authorization server, and it names port 0, which no server listens on.`);
+    }
+    if (url.protocol === "https:") {
+        return issuer;
+    }
+    if (url.protocol === "http:" && LOOPBACK_SERVER_HOSTS.has(url.hostname)) {
+        return issuer;
+    }
+    if (url.protocol === "http:" && url.hostname === "localhost") {
+        url.hostname = "127.0.0.1";
+        return refuse(`\`mcp\` advertises Access's issuer (${issuer}, from \`${baseURLAt}\`) as the MCP endpoint's OAuth authorization server, and an http one must be written as an address of this machine, not a name that is resolved (and may resolve elsewhere): set \`${baseURLAt}\` to ${url.origin}.`);
+    }
+    return refuse(`\`mcp\` advertises Access's issuer (${issuer}, from \`${baseURLAt}\`) as the MCP endpoint's OAuth authorization server, which must be https (or, on this machine, \`http://127.0.0.1\` or \`http://[::1]\`): set \`${baseURLAt}\` to its https URL.`);
+};

package/dist/oauth/access-token.verifier.d.ts

@@ -0,0 +1,66 @@
+import { type JSONWebKeySet } from "jose";
+import type { AccessClaimsSource } from "../access/claims.mapper.js";
+type ClaimsMap = {
+    readonly [claim: string]: string | number | boolean;
+};
+type AccessTokenVerifierSource = {
+    /** The published key set: `{ keys: [...] }`. */
+    readonly keys: () => Promise<JSONWebKeySet>;
+    /** The tokens' `iss`: the instance's fixed issuer. */
+    readonly issuer: string;
+    /** The resource's URL: the audience every token must name. */
+    readonly resource: string;
+    /** The provider's UserInfo URL, which a token asked with `openid` names beside the resource; `undefined` when Better Auth's base URL follows the request. */
+    readonly userInfo: string | undefined;
+    /** Better Auth's context, once Better Auth is built. */
+    readonly context: () => Promise<unknown>;
+    /** A user's claims, as a token `GET /token` issued now would carry them. */
+    readonly claimsFor: (source: AccessClaimsSource) => Promise<ClaimsMap>;
+    /** Milliseconds since the epoch; a test passes its own clock. */
+    readonly now?: () => number;
+};
+/** What an access token grants: the client it was issued to, and its scopes. */
+export type TokenGrant = {
+    readonly clientId: string;
+    readonly scopes: ReadonlySet<string>;
+};
+/** Who an access token acts for, and what it grants. */
+export type TokenCaller = {
+    readonly identity: {
+        readonly sub: string;
+        readonly claims: ClaimsMap;
+    };
+    readonly grant: TokenGrant;
+};
+export type AccessTokenVerifier = {
+    /** The caller an access token for the resource proves, or `null` for any other token. */
+    verify(token: string): Promise<TokenCaller | null>;
+};
+export declare const createAccessTokenVerifier: (source: AccessTokenVerifierSource) => AccessTokenVerifier;
+/**
+ * The provider's UserInfo URL, which a token asked with `openid` names as its second
+ * audience: Better Auth's base URL (with its base path) and `/oauth2/userinfo`.
+ * `undefined` when the base URL follows the request (a dynamic `baseURL`): such a
+ * token then names an audience Access cannot know, and is refused.
+ */
+export declare const userInfoAudience: (block: {
+    readonly baseURL?: unknown;
+    readonly basePath?: unknown;
+}, modules: {
+    readonly getBaseURL: (baseURL: string | undefined, basePath: string | undefined) => string | undefined;
+    readonly isDynamicBaseURLConfig: (baseURL: unknown) => boolean;
+}) => string | undefined;
+/**
+ * `access.mcp` over the MCP endpoint's verifier: the framework's `mcp.authorization`, frozen,
+ * with exactly the two members the framework takes.
+ */
+export declare const mcpAuthorizationOf: (agents: AccessTokenVerifier, server: string) => {
+    readonly servers: readonly [string];
+    verify(token: string): Promise<{
+        readonly sub: string;
+        readonly claims: ClaimsMap;
+        readonly clientId: string;
+        readonly scopes: readonly string[];
+    } | null>;
+};
+export {};

package/dist/oauth/access-token.verifier.js

@@ -0,0 +1,201 @@
+// Verifies the access tokens Better Auth's OAuth provider (`@better-auth/oauth-provider`)
+// issues for one resource (RFC 8707), and finds who each acts for. Access issues no
+// token itself: it reads the provider's. Two resources use it: the MCP endpoint
+// (`mcp`, whose callers are agents) and the service itself when it opts in to its
+// own audience (`audience`).
+//
+// A token passes when it is a JWT access token (`typ: "at+jwt"`, RFC 9068) signed
+// with the keys `jwt()` publishes, by an algorithm `jwt()` signs with
+// (`JWT_ALGORITHMS`), with the instance's issuer, current, issued for the one
+// resource alone (`aud` the resource; with `openid` beside it, the provider's
+// UserInfo endpoint too, and nothing else), to a client (`azp`, `client_id`) for a
+// user (`sub`, never the client itself: a client-credentials token acts for no one),
+// in the session the user consented in (`sid`), with its scopes, and not bound to a
+// DPoP key (`cnf`): this endpoint reads a bearer token and no proof, and a bound
+// token presented without one is refused (RFC 9449 section 7.1).
+//
+// Then, on every request, what the provider's own introspection checks, and more: the
+// client exists and is not disabled; the resource is still one of the provider's (an
+// `oauthResource` row: a deleted one takes no token, as the provider's introspection
+// refuses it); the session the token was issued in has not ended, and is not bound to
+// a kiosk device (`kioskDeviceId`: such a session is issued no token, whatever route
+// minted one, since a token would act for the till's user off the device and past its
+// lock and idle timeout); the user exists;
+// and, unless the client is a trusted one that skips consent, the user's consent to
+// that client still covers the token's scopes and its resource, so revoking consent
+// stops the agent at once. A consent stored under a reference (the provider's
+// `postLogin.consentReferenceId`, which Access refuses) never counts: a JWT access
+// token does not say which reference it was consented under. The claims are the
+// user's now, as a token `GET /token` issued now would carry them: a role taken away
+// or a ban takes effect on the agent's next request, not when its token expires.
+//
+// A token that fails any of this is `null`. The token is read and never sent on:
+// nothing here calls another service with it.
+import { errors, jwtVerify } from "jose";
+import { createKeySetCache } from "../access/key-set.cache.js";
+import { CLOCK_TOLERANCE_S, JWT_ALGORITHMS } from "../access/token.verifier.js";
+const isNonEmpty = (value) => typeof value === "string" && value !== "";
+/** Whether `aud` names the resource alone (with `openid`, the UserInfo endpoint beside it). */
+const forResource = (aud, resource, userInfo) => {
+    if (aud === resource) {
+        return true;
+    }
+    return (Array.isArray(aud) &&
+        aud.length === 2 &&
+        userInfo !== undefined &&
+        userInfo !== resource &&
+        aud.includes(resource) &&
+        aud.includes(userInfo));
+};
+const scopesOf = (scope) => typeof scope === "string"
+    ? scope.split(" ").filter((value) => value !== "")
+    : undefined;
+const timeOf = (value) => value instanceof Date
+    ? value.getTime()
+    : typeof value === "string" || typeof value === "number"
+        ? new Date(value).getTime()
+        : Number.NaN;
+export const createAccessTokenVerifier = (source) => {
+    const now = source.now ?? (() => Date.now());
+    const keySet = createKeySetCache(source.keys, now);
+    /** Who the token's claims name, when the store still says they may act: the user, and the session it was issued in. */
+    const live = async (claims) => {
+        const { adapter, internalAdapter } = (await source.context());
+        const [client, resource, user, session, consents] = await Promise.all([
+            adapter.findOne({
+                model: "oauthClient",
+                where: [{ field: "clientId", value: claims.clientId }],
+            }),
+            adapter.findOne({
+                model: "oauthResource",
+                where: [{ field: "identifier", value: source.resource }],
+            }),
+            internalAdapter.findUserById(claims.sub),
+            adapter.findOne({
+                model: "session",
+                where: [{ field: "id", value: claims.sid }],
+            }),
+            adapter.findMany({
+                model: "oauthConsent",
+                where: [
+                    { field: "clientId", value: claims.clientId },
+                    { field: "userId", value: claims.sub },
+                ],
+            }),
+        ]);
+        if (client === null ||
+            client.disabled === true ||
+            resource === null ||
+            user === null) {
+            return null;
+        }
+        if (session === null ||
+            !(timeOf(session.expiresAt) > now()) ||
+            (typeof session.kioskDeviceId === "string" &&
+                session.kioskDeviceId !== "")) {
+            return null;
+        }
+        if (client.skipConsent !== true &&
+            !consents.some((consent) => (consent.referenceId === undefined ||
+                consent.referenceId === null ||
+                consent.referenceId === "") &&
+                Array.isArray(consent.resources) &&
+                consent.resources.includes(source.resource) &&
+                Array.isArray(consent.scopes) &&
+                claims.scopes.every((scope) => consent.scopes.includes(scope)))) {
+            return null;
+        }
+        return { user, session };
+    };
+    return {
+        async verify(token) {
+            let payload;
+            try {
+                ({ payload } = await keySet.withKeys((keys) => jwtVerify(token, keys, {
+                    typ: "at+jwt",
+                    issuer: source.issuer,
+                    algorithms: [...JWT_ALGORITHMS],
+                    requiredClaims: [
+                        "sub",
+                        "aud",
+                        "exp",
+                        "iat",
+                        "azp",
+                        "client_id",
+                        "scope",
+                        "sid",
+                    ],
+                    clockTolerance: CLOCK_TOLERANCE_S,
+                    currentDate: new Date(now()),
+                })));
+            }
+            catch (error) {
+                if (error instanceof errors.JOSEError) {
+                    return null;
+                }
+                throw error;
+            }
+            const { sub, aud, azp, client_id: clientId, sid, cnf } = payload;
+            const scopes = scopesOf(payload.scope);
+            if (!isNonEmpty(sub) ||
+                !isNonEmpty(azp) ||
+                clientId !== azp ||
+                sub === azp ||
+                cnf !== undefined ||
+                scopes === undefined ||
+                !isNonEmpty(sid) ||
+                !forResource(aud, source.resource, source.userInfo)) {
+                return null;
+            }
+            const found = await live({
+                sub,
+                clientId: azp,
+                sid,
+                scopes,
+            });
+            if (found === null) {
+                return null;
+            }
+            return {
+                identity: { sub, claims: await source.claimsFor(found) },
+                grant: { clientId: azp, scopes: new Set(scopes) },
+            };
+        },
+    };
+};
+/**
+ * The provider's UserInfo URL, which a token asked with `openid` names as its second
+ * audience: Better Auth's base URL (with its base path) and `/oauth2/userinfo`.
+ * `undefined` when the base URL follows the request (a dynamic `baseURL`): such a
+ * token then names an audience Access cannot know, and is refused.
+ */
+export const userInfoAudience = (block, modules) => {
+    if (modules.isDynamicBaseURLConfig(block.baseURL)) {
+        return undefined;
+    }
+    const base = modules.getBaseURL(typeof block.baseURL === "string" ? block.baseURL : undefined, typeof block.basePath === "string" ? block.basePath : undefined);
+    return base === undefined
+        ? undefined
+        : `${base.replace(/\/+$/, "")}/oauth2/userinfo`;
+};
+/**
+ * `access.mcp` over the MCP endpoint's verifier: the framework's `mcp.authorization`, frozen,
+ * with exactly the two members the framework takes.
+ */
+export const mcpAuthorizationOf = (agents, server) => Object.freeze({
+    servers: Object.freeze([server]),
+    async verify(token) {
+        if (typeof token !== "string") {
+            return null;
+        }
+        const caller = await agents.verify(token);
+        return caller === null
+            ? null
+            : Object.freeze({
+                sub: caller.identity.sub,
+                claims: caller.identity.claims,
+                clientId: caller.grant.clientId,
+                scopes: Object.freeze([...caller.grant.scopes]),
+            });
+    },
+});

package/dist/oauth/oauth-provider.hardening.d.ts

@@ -0,0 +1,62 @@
+/** How a refusal names where the plugins are. */
+type ProviderPlace = {
+    /** Where the app lists Better Auth's plugins: `betterAuth.plugins`, `plugins`. */
+    readonly at: string;
+    /** The Access plugin itself, in a list it is part of (`aventaraAccess()`): it must come before the provider. */
+    readonly own?: unknown;
+};
+/** What Access reads the provider's tokens for. */
+type ProviderUse = {
+    /** The resources whose tokens Access reads: the MCP endpoint, the service's own audience. */
+    readonly resources: readonly string[];
+    /** What reads them, as a refusal names it: `mcp`, `audience`, or both. */
+    readonly by: string;
+    /** With `mcp`: the MCP endpoint, whose agents read and write with Access's scopes. */
+    readonly mcp: string | undefined;
+    /** With `audience`: the service's own audience. */
+    readonly audience: string | undefined;
+    /** `mcp.openRegistration`: the provider's open client registration is taken. */
+    readonly openRegistration: boolean;
+};
+/**
+ * The OAuth provider among `plugins`, checked: present once, a version in range,
+ * and the options the tokens Access reads need.
+ */
+export declare const checkOAuthProvider: (plugins: readonly unknown[], use: ProviderUse, place: ProviderPlace) => void;
+/**
+ * A `before` hook (Better Auth's plugin hook shape) that refuses an authorization
+ * request without PKCE: a `code_challenge` made with the SHA-256 method (`code_challenge_method`).
+ * It reads the request's parameters as the provider does (a `POST`'s body, else the
+ * query; a sign-in resuming the request carries the signed query it began with). A
+ * request by reference (`request_uri`) is refused whatever else it carries: the
+ * provider would read its parameters from the reference, not from the request.
+ */
+export declare const pkceGuard: (modules: {
+    readonly createAuthMiddleware: (handler: (context: never) => Promise<unknown>) => unknown;
+    readonly APIError: new (status: string, body?: {
+        readonly [key: string]: unknown;
+    }) => Error;
+}) => {
+    matcher: (context: {
+        readonly path?: unknown;
+    } | undefined) => boolean;
+    handler: unknown;
+};
+/**
+ * A resource Access reads the provider's tokens for, checked: an absolute https URL
+ * (or http on this machine) with no credentials, query or fragment, written as a
+ * protected resource's metadata writes it (the origin, then the path with no trailing
+ * slash), and not the issuer itself, the audience of the tokens `GET /token` issues.
+ */
+export declare const checkResourceUrl: (resource: unknown, at: string, issuer: string) => string;
+/**
+ * What Access reads Better Auth's OAuth provider's tokens for, when it reads any.
+ * `userInfo` is the provider's UserInfo URL, when Access knows it: no resource Access
+ * reads tokens for may be it, since a token asked with `openid` names it beside its
+ * resource.
+ */
+export declare const oauthUseOf: (mcp: {
+    readonly resource: string;
+    readonly openRegistration: boolean;
+} | undefined, audience: string | undefined, userInfo: string | undefined) => ProviderUse | undefined;
+export {};

package/dist/oauth/oauth-provider.hardening.js

@@ -0,0 +1,261 @@
+// What Access holds Better Auth's OAuth provider (`@better-auth/oauth-provider`) to
+// when it reads the provider's tokens (`mcp`, `audience`), and the one hook it adds
+// to it. The provider is the app's, in Better Auth's plugins with its own options,
+// passed through untouched, as plain Better Auth takes it: Access issues no token and
+// serves no OAuth route. It refuses to start on options that would let a token's
+// authorization fall short of what the MCP authorization specification and OAuth 2.1
+// ask, rather than change them quietly (fail closed, as the GHSA-fmh4 guard does):
+//
+// - the exact provider version Access is built and tested against;
+// - JWT access tokens (`disableJwtPlugin` off): `access.mcp.verify` reads the
+//   audience, client and scopes from the token, signed with the keys `jwt()` publishes;
+// - each resource Access reads tokens for (the MCP endpoint, the service's own
+//   `audience`) among the provider's `resources`, so a token can name it as its
+//   audience (RFC 8707);
+// - `aventara:read` among its `scopes`, the scope a token reads with;
+// - refresh tokens rotated strictly (`refreshTokenReuseInterval: 0`, the provider's
+//   own default): a spent refresh token is never answered again, however soon;
+// - exact redirect URI matching (no `validateRedirectUri`), which the provider does
+//   by default (RFC 9700, section 2.1; a native client's loopback redirect may use another
+//   port, RFC 8252, section 7.3);
+// - no authorization request by reference (`requestUriResolver`): its parameters
+//   come from the resolver, never the request the PKCE hook reads;
+// - no consent under a reference (`postLogin.consentReferenceId`): a JWT access token
+//   does not carry the reference, so Access could not tell which consent it was
+//   given under;
+// - with `audience`, each client linked to the resources it may ask for
+//   (`enforcePerClientResources`, the provider's default): a client registered for
+//   one resource gets no token for another;
+// - with `mcp` and `audience`, the service's audience never linked to a client as it
+//   registers (`clientRegistrationDefaultResources`,
+//   `clientRegistrationAllowedResources`): an agent's client that registers itself is
+//   for the MCP endpoint alone, and a token it refreshed to the service would pass
+//   for the service's own;
+// - no open dynamic client registration (`allowUnauthenticatedClientRegistration`),
+//   unless `mcp.openRegistration` takes it: such a client is whoever it says it is.
+//   Client ID Metadata Documents (`@better-auth/cimd`) register a client as the domain
+//   its document is served from; with the plugin there, a version in Access's range.
+//
+// And, on every authorization request, PKCE with its SHA-256 method (`pkceGuard`): the provider
+// asks it of public clients and most confidential ones, and lets a confidential
+// OpenID request with a `nonce` (or a client created with `require_pkce: false`) go
+// without; while Access reads its tokens, no request does, and none by reference
+// (`request_uri`). The hook refuses a request before the provider runs, as the
+// `service` profile's hook refuses a session-starting route; it issues nothing.
+import { AccessError } from "../access/access.error.js";
+import { normalisedId } from "../access/better-auth.hardening.js";
+import { BETTER_AUTH_RANGE, BETTER_AUTH_RANGE_SAID, inBetterAuthRange, } from "../access/better-auth.range.js";
+import { MCP_READ_SCOPE, MCP_WRITE_SCOPE } from "../mcp/agent.grant.js";
+/** The OAuth provider's plugin id. */
+const OAUTH_PROVIDER_ID = "oauth-provider";
+/** The Client ID Metadata Document plugin's id. */
+const CIMD_ID = "cimd";
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+const listOf = (value) => Array.isArray(value) ? value : [];
+/**
+ * The OAuth provider among `plugins`, checked: present once, a version in range,
+ * and the options the tokens Access reads need.
+ */
+export const checkOAuthProvider = (plugins, use, place) => {
+    const { at } = place;
+    const listed = use.resources.map((resource) => `"${resource}"`).join(", ");
+    const found = plugins.filter((plugin) => normalisedId(plugin?.id) ===
+        OAUTH_PROVIDER_ID);
+    // An agent's client registers itself for the MCP endpoint alone; a client the
+    // service's audience takes is linked to it one by one.
+    const install = `\`oauthProvider({ loginPage, consentPage, scopes: ["${MCP_READ_SCOPE}", "${MCP_WRITE_SCOPE}", "offline_access"], resources: [${listed}]${use.mcp === undefined ? "" : `, clientRegistrationDefaultResources: ["${use.mcp}"]`} })\` from @better-auth/oauth-provider${use.audience === undefined ? "" : `, and link each client the service takes to "${use.audience}" (\`auth.api.adminLinkClientResource\`)`}`;
+    if (found.length === 0) {
+        refuse(`\`${use.by}\` reads the access tokens Better Auth's OAuth provider issues, and ${at} has none: add ${install}.`);
+    }
+    if (found.length > 1) {
+        refuse(`${at} holds ${found.length} OAuth providers (plugin id "${OAUTH_PROVIDER_ID}"); Better Auth runs one. Keep one.`);
+    }
+    const provider = found[0];
+    if (!inBetterAuthRange(provider.version)) {
+        throw new AccessError("ACCESS_BETTER_AUTH_VERSION", `\`${use.by}\` runs on @better-auth/oauth-provider ${BETTER_AUTH_RANGE_SAID}, and ${at} holds ${typeof provider.version === "string" ? provider.version : "a version Access cannot read"}: npm install @better-auth/oauth-provider@${BETTER_AUTH_RANGE}`);
+    }
+    if (place.own !== undefined) {
+        const own = plugins.indexOf(place.own);
+        if (own > plugins.indexOf(provider)) {
+            refuse(`${at} lists the OAuth provider before aventaraAccess(): Better Auth starts its plugins in order, and the provider reads, as it starts, the jwt() the Access plugin carries. Put aventaraAccess() first.`);
+        }
+    }
+    const options = provider.options ?? {};
+    if (options.disableJwtPlugin === true) {
+        refuse(`\`${use.by}\` reads a token's audience, client and scopes from the token, signed with the keys jwt() publishes, and the OAuth provider's \`disableJwtPlugin: true\` issues opaque tokens: remove it.`);
+    }
+    const resources = Array.isArray(options.resources) ? options.resources : [];
+    for (const resource of use.resources) {
+        if (!resources.some((entry) => entry === resource ||
+            entry?.identifier ===
+                resource)) {
+            refuse(`the OAuth provider issues a token for ${resource} only when its \`resources\` list it (RFC 8707): add "${resource}" to them.`);
+        }
+    }
+    const scopes = listOf(options.scopes);
+    if (!scopes.includes(MCP_READ_SCOPE)) {
+        refuse(use.mcp !== undefined
+            ? `an agent reads through the MCP endpoint with the scope "${MCP_READ_SCOPE}" (and writes with "${MCP_WRITE_SCOPE}"), and the OAuth provider's \`scopes\` have neither: add them.`
+            : `a token addressed to the service reads with the scope "${MCP_READ_SCOPE}" (and writes with "${MCP_WRITE_SCOPE}"), and the OAuth provider's \`scopes\` have neither: add them.`);
+    }
+    if (options.refreshTokenReuseInterval !== 0) {
+        refuse(`the OAuth provider answers a spent refresh token again for ${String(options.refreshTokenReuseInterval)} seconds (\`refreshTokenReuseInterval\`): refresh tokens rotate strictly while Access reads the provider's tokens, so set it to 0.`);
+    }
+    if (options.validateRedirectUri !== undefined) {
+        refuse("the OAuth provider's `validateRedirectUri` accepts redirect URIs the client did not register: while Access reads the provider's tokens, an authorization code goes only to a redirect URI that matches a registered one exactly. Remove it.");
+    }
+    if (options.requestUriResolver !== undefined) {
+        refuse("the OAuth provider's `requestUriResolver` takes an authorization request by reference (`request_uri`), whose parameters Access cannot hold to PKCE: while Access reads the provider's tokens, every authorization request carries its own. Remove it.");
+    }
+    if (options.postLogin !== undefined &&
+        options.postLogin !== null &&
+        options.postLogin.consentReferenceId !== undefined) {
+        refuse("the OAuth provider's `postLogin.consentReferenceId` stores each consent under a reference, and a JWT access token does not say which: Access could not tell whether the consent a token was issued under still stands. Remove it.");
+    }
+    if (use.audience !== undefined) {
+        if (options.enforcePerClientResources === false) {
+            refuse(`the OAuth provider's \`enforcePerClientResources: false\` lets any client ask for a token addressed to the service (${use.audience}): with \`audience\`, a client gets one only when it is linked to it. Remove it.`);
+        }
+        if (use.mcp !== undefined) {
+            for (const option of [
+                "clientRegistrationDefaultResources",
+                "clientRegistrationAllowedResources",
+            ]) {
+                if (listOf(options[option]).includes(use.audience)) {
+                    refuse(`the OAuth provider's \`${option}\` links the service's audience (${use.audience}) to a client as it registers: an agent's client that registers itself would be issued tokens that pass for the service's own. List only the MCP endpoint there ("${use.mcp}"), and link each client the service takes to its audience yourself (\`auth.api.adminLinkClientResource\`).`);
+                }
+            }
+        }
+    }
+    if (options.allowUnauthenticatedClientRegistration === true &&
+        !use.openRegistration) {
+        refuse(use.mcp !== undefined
+            ? "the OAuth provider's `allowUnauthenticatedClientRegistration: true` registers any client that asks, as whoever it says it is: its name, logo and redirect URI. Prefer Client ID Metadata Documents (`cimd()` from @better-auth/cimd), whose client is the domain its document is served from; to take open registration anyway, set `mcp.openRegistration: true`."
+            : "the OAuth provider's `allowUnauthenticatedClientRegistration: true` registers any client that asks, as whoever it says it is, and `audience` takes no such client: register clients signed in, with an initial access token, or by Client ID Metadata Documents (`cimd()` from @better-auth/cimd). Remove it.");
+    }
+    const cimd = plugins.find((plugin) => normalisedId(plugin?.id) ===
+        CIMD_ID);
+    if (cimd !== undefined && !inBetterAuthRange(cimd.version)) {
+        throw new AccessError("ACCESS_BETTER_AUTH_VERSION", `\`${use.by}\` runs on @better-auth/cimd ${BETTER_AUTH_RANGE_SAID}, and ${at} holds ${typeof cimd.version === "string" ? cimd.version : "a version Access cannot read"}: npm install @better-auth/cimd@${BETTER_AUTH_RANGE}`);
+    }
+};
+/** The OAuth provider's authorization endpoint, as Better Auth's hooks see its path. */
+const AUTHORIZE_PATH = "/oauth2/authorize";
+/**
+ * A `before` hook (Better Auth's plugin hook shape) that refuses an authorization
+ * request without PKCE: a `code_challenge` made with the SHA-256 method (`code_challenge_method`).
+ * It reads the request's parameters as the provider does (a `POST`'s body, else the
+ * query; a sign-in resuming the request carries the signed query it began with). A
+ * request by reference (`request_uri`) is refused whatever else it carries: the
+ * provider would read its parameters from the reference, not from the request.
+ */
+export const pkceGuard = (modules) => ({
+    matcher: (context) => context?.path === AUTHORIZE_PATH,
+    handler: modules.createAuthMiddleware(async (given) => {
+        const context = given;
+        const settings = context.authorizeSettings ?? { isAuthorize: true };
+        const source = context.method === "POST" && settings.isAuthorize === true
+            ? context.body
+            : context.query;
+        const params = (typeof source === "object" && source !== null ? source : {});
+        const query = (typeof context.query === "object" && context.query !== null
+            ? context.query
+            : {});
+        if (params.request_uri !== undefined || query.request_uri !== undefined) {
+            throw new modules.APIError("BAD_REQUEST", {
+                error: "invalid_request",
+                error_description: "This authorization server takes no request by reference: send the authorization request's parameters, with code_challenge and code_challenge_method=S256.",
+            });
+        }
+        const { code_challenge: challenge, code_challenge_method: method } = params;
+        if (typeof challenge !== "string" ||
+            challenge === "" ||
+            method !== "S256") {
+            throw new modules.APIError("BAD_REQUEST", {
+                error: "invalid_request",
+                error_description: "This authorization server requires PKCE: send code_challenge with code_challenge_method=S256.",
+            });
+        }
+    }),
+});
+/** The hosts a resource served over http may name: this machine. */
+const LOOPBACK_RESOURCE_HOSTS = new Set([
+    "localhost",
+    "127.0.0.1",
+    "[::1]",
+]);
+/**
+ * A resource Access reads the provider's tokens for, checked: an absolute https URL
+ * (or http on this machine) with no credentials, query or fragment, written as a
+ * protected resource's metadata writes it (the origin, then the path with no trailing
+ * slash), and not the issuer itself, the audience of the tokens `GET /token` issues.
+ */
+export const checkResourceUrl = (resource, at, issuer) => {
+    if (typeof resource !== "string") {
+        return refuse(`\`${at}\` is an absolute URL (\`"https://app.example.com/mcp"\`); it was ${JSON.stringify(resource)}.`);
+    }
+    let url;
+    try {
+        url = new URL(resource);
+    }
+    catch {
+        return refuse(`\`${at}\` is an absolute URL (\`"https://app.example.com/mcp"\`); it was ${JSON.stringify(resource)}.`);
+    }
+    if (!(url.protocol === "https:" ||
+        (url.protocol === "http:" && LOOPBACK_RESOURCE_HOSTS.has(url.hostname)))) {
+        return refuse(`\`${at}\` must be an https URL (or http on this machine: \`localhost\`, \`127.0.0.1\`, \`[::1]\`); it was ${JSON.stringify(resource)}.`);
+    }
+    if (url.username !== "" ||
+        url.password !== "" ||
+        resource.includes("?") ||
+        resource.includes("#") ||
+        url.pathname.includes("//")) {
+        return refuse(`\`${at}\` names one resource alone: no credentials, query, fragment or empty path segment; it was ${JSON.stringify(resource)}.`);
+    }
+    const canonical = `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+    if (resource !== canonical) {
+        return refuse(`\`${at}\` must be written as the resource's metadata writes it, which a client sends back verbatim as its resource indicator: ${canonical}`);
+    }
+    if (canonical === issuer) {
+        return refuse(`\`${at}\` is Access's issuer (${issuer}), the audience of the tokens \`GET /token\` issues: a token for one must never pass for the other. Name the resource by its own path (\`${issuer}/mcp\`, \`${issuer}/api\`).`);
+    }
+    return canonical;
+};
+/**
+ * What Access reads Better Auth's OAuth provider's tokens for, when it reads any.
+ * `userInfo` is the provider's UserInfo URL, when Access knows it: no resource Access
+ * reads tokens for may be it, since a token asked with `openid` names it beside its
+ * resource.
+ */
+export const oauthUseOf = (mcp, audience, userInfo) => {
+    if (mcp === undefined && audience === undefined) {
+        return undefined;
+    }
+    if (mcp !== undefined && mcp.resource === audience) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "`audience` is the MCP endpoint (`mcp.resource`): an agent's token would pass for the service's own. Give the service its own URL.");
+    }
+    for (const [at, resource] of [
+        ["mcp.resource", mcp?.resource],
+        ["audience", audience],
+    ]) {
+        if (resource !== undefined && resource === userInfo) {
+            throw new AccessError("ACCESS_OPTIONS_INVALID", `\`${at}\` is the OAuth provider's UserInfo endpoint (${userInfo}), which every token asked with \`openid\` names beside its own resource: such a token would pass for it. Name the resource by its own path.`);
+        }
+    }
+    return {
+        resources: [
+            ...(mcp === undefined ? [] : [mcp.resource]),
+            ...(audience === undefined ? [] : [audience]),
+        ],
+        by: mcp !== undefined && audience !== undefined
+            ? "mcp` and `audience"
+            : mcp !== undefined
+                ? "mcp"
+                : "audience",
+        mcp: mcp?.resource,
+        audience,
+        openRegistration: mcp?.openRegistration === true,
+    };
+};