@better-auth/oauth-provider 1.7.0-beta.0 → 1.7.0-beta.10

package/dist/oauth-ScTJEcFV.d.mts

@@ -0,0 +1,2849 @@
+import * as z from "zod";
+import { PrivateKeyJwtSigningAlgorithm } from "@better-auth/core/oauth2";
+import { JWTPayload } from "jose";
+import { JWSAlgorithms } from "better-auth/plugins";
+import { InferOptionSchema, Session, User } from "better-auth/types";
+import { GenericEndpointContext, LiteralString } from "@better-auth/core";
+
+//#region src/schema.d.ts
+declare const schema: {
+  oauthClient: {
+    modelName: string;
+    fields: {
+      clientId: {
+        type: "string";
+        unique: true;
+        required: true;
+      };
+      clientSecret: {
+        type: "string";
+        required: false;
+      };
+      disabled: {
+        type: "boolean";
+        defaultValue: false;
+        required: false;
+      };
+      skipConsent: {
+        type: "boolean";
+        required: false;
+      };
+      enableEndSession: {
+        type: "boolean";
+        required: false;
+      };
+      subjectType: {
+        type: "string";
+        required: false;
+      };
+      scopes: {
+        type: "string[]";
+        required: false;
+      };
+      userId: {
+        type: "string";
+        required: false;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      createdAt: {
+        type: "date";
+        required: false;
+      };
+      updatedAt: {
+        type: "date";
+        required: false;
+      };
+      name: {
+        type: "string";
+        required: false;
+      };
+      uri: {
+        type: "string";
+        required: false;
+      };
+      icon: {
+        type: "string";
+        required: false;
+      };
+      contacts: {
+        type: "string[]";
+        required: false;
+      };
+      tos: {
+        type: "string";
+        required: false;
+      };
+      policy: {
+        type: "string";
+        required: false;
+      };
+      softwareId: {
+        type: "string";
+        required: false;
+      };
+      softwareVersion: {
+        type: "string";
+        required: false;
+      };
+      softwareStatement: {
+        type: "string";
+        required: false;
+      };
+      redirectUris: {
+        type: "string[]";
+        required: true;
+      };
+      postLogoutRedirectUris: {
+        type: "string[]";
+        required: false;
+      };
+      backchannelLogoutUri: {
+        type: "string";
+        required: false;
+      };
+      backchannelLogoutSessionRequired: {
+        type: "boolean";
+        required: false;
+      };
+      tokenEndpointAuthMethod: {
+        type: "string";
+        required: false;
+      };
+      jwks: {
+        type: "string";
+        required: false;
+      };
+      jwksUri: {
+        type: "string";
+        required: false;
+      };
+      grantTypes: {
+        type: "string[]";
+        required: false;
+      };
+      responseTypes: {
+        type: "string[]";
+        required: false;
+      };
+      public: {
+        type: "boolean";
+        required: false;
+      };
+      type: {
+        type: "string";
+        required: false;
+      };
+      requirePKCE: {
+        type: "boolean";
+        required: false;
+      };
+      dpopBoundAccessTokens: {
+        type: "boolean";
+        required: false;
+        defaultValue: false;
+      };
+      referenceId: {
+        type: "string";
+        required: false;
+      };
+      metadata: {
+        type: "json";
+        required: false;
+      };
+    };
+  };
+  /**
+   * A protected resource the AS issues access tokens for.
+   *
+   * Promotes protected resources into a first-class persisted entity with
+   * per-resource token policy. A null value
+   * on any policy column means "inherit the plugin-level default at token
+   * issuance time" — admins can later override without re-seeding.
+   *
+   * @see RFC 8707 (Resource Indicators) — `identifier` is the `resource` parameter value
+   * @see RFC 9068 §2.2 — `customClaims` cannot override reserved JWT claims (enforced server-side)
+   */
+  oauthResource: {
+    modelName: string;
+    fields: {
+      identifier: {
+        type: "string";
+        required: true;
+        unique: true;
+      };
+      name: {
+        type: "string";
+        required: true;
+      };
+      accessTokenTtl: {
+        type: "number";
+        required: false;
+      };
+      refreshTokenTtl: {
+        type: "number";
+        required: false;
+      };
+      signingAlgorithm: {
+        type: "string";
+        required: false;
+      };
+      signingKeyId: {
+        type: "string";
+        required: false;
+      };
+      allowedScopes: {
+        type: "string[]";
+        required: false;
+      };
+      customClaims: {
+        type: "json";
+        required: false;
+      };
+      dpopBoundAccessTokensRequired: {
+        type: "boolean";
+        required: false;
+        defaultValue: false;
+      };
+      disabled: {
+        type: "boolean";
+        required: false;
+        defaultValue: false;
+      };
+      createdAt: {
+        type: "date";
+        required: false;
+      };
+      updatedAt: {
+        type: "date";
+        required: false;
+      };
+      policyVersion: {
+        type: "number";
+        required: false;
+        defaultValue: number;
+      };
+      metadata: {
+        type: "json";
+        required: false;
+      };
+    };
+  };
+  /**
+   * Join table — which clients are allowed to request which resources.
+   *
+   * Authoritative only when `enforcePerClientResources: true` on plugin options.
+   * When the flag is off, clients implicitly have access to all enabled resources
+   * (preserves pre-entity behavior).
+   *
+   * Composite uniqueness on `(clientId, resourceId)` is load-bearing — the
+   * `enforcePerClientResources` linkage check assumes one row per pair.
+   *
+   * Better Auth's schema layer doesn't expose composite-UNIQUE syntax (no
+   * way to declare `UNIQUE(clientId, resourceId)` at the column level). To
+   * enforce it at the database level for free, we set the row's `id` to a
+   * deterministic `${clientId}::${resourceId}` value at write time and let
+   * the implicit `UNIQUE` constraint on the primary key catch duplicates
+   * (see `buildClientResourceLinkId` and the `forceAllowId: true` flag on
+   * the `adapter.create` call in `oauthResource/endpoints.ts`). The double
+   * colon separator is chosen because `::` cannot appear in either a
+   * client_id (URL-safe random string) or a resource identifier (RFC 8707
+   * absolute URI — `::` would be an IPv6 form rejected by the validator),
+   * so the encoding is collision-free.
+   *
+   * Concurrent inserts of the same pair surface as a UNIQUE-constraint
+   * error which the endpoint catches and converts to a 200 "alreadyLinked"
+   * response (idempotency).
+   */
+  oauthClientResource: {
+    modelName: string;
+    fields: {
+      clientId: {
+        type: "string";
+        required: true;
+        references: {
+          model: string;
+          field: string;
+          onDelete: "cascade";
+        };
+        index: true;
+      };
+      resourceId: {
+        type: "string";
+        required: true;
+        references: {
+          model: string;
+          field: string;
+          onDelete: "cascade";
+        };
+        index: true;
+      };
+      metadata: {
+        type: "json";
+        required: false;
+      };
+      createdAt: {
+        type: "date";
+        required: false;
+      };
+    };
+  };
+  /**
+   * An opaque refresh token created with "offline_access"
+   *
+   * Refresh tokens are linked to a session.
+   */
+  oauthRefreshToken: {
+    fields: {
+      token: {
+        type: "string";
+        required: true;
+        unique: true;
+      };
+      clientId: {
+        type: "string";
+        required: true;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      sessionId: {
+        type: "string";
+        required: false;
+        references: {
+          model: string;
+          field: string;
+          onDelete: "set null";
+        };
+        index: true;
+      };
+      userId: {
+        type: "string";
+        required: true;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      referenceId: {
+        type: "string";
+        required: false;
+      };
+      authorizationCodeId: {
+        type: "string";
+        required: false;
+        index: true;
+      };
+      resources: {
+        type: "string[]";
+        required: false;
+      };
+      requestedUserInfoClaims: {
+        type: "string[]";
+        required: false;
+      };
+      expiresAt: {
+        type: "date";
+      };
+      createdAt: {
+        type: "date";
+      };
+      revoked: {
+        type: "date";
+        required: false;
+      };
+      rotatedAt: {
+        type: "date";
+        required: false;
+      };
+      rotationReplayResponse: {
+        type: "string";
+        required: false;
+      };
+      rotationReplayExpiresAt: {
+        type: "date";
+        required: false;
+      };
+      authTime: {
+        type: "date";
+        required: false;
+      };
+      confirmation: {
+        type: "json";
+        required: false;
+      };
+      scopes: {
+        type: "string[]";
+        required: true;
+      };
+    };
+  };
+  /**
+   * An opaque access token sent when there is no resource audience claim
+   * to assigned to the JWT.
+   *
+   * Access tokens are linked to a session, better-auth
+   * authors SHALL always check for valid session!
+   *
+   * AccessTokens SHALL only be created at refresh,
+   * destroyed at revoke, and read at introspection.
+   * NEVER update an access token! Typically a refresh and
+   * revoke (if not expired) may want to occur at the same time.
+   */
+  oauthAccessToken: {
+    modelName: string;
+    fields: {
+      token: {
+        type: "string";
+        unique: true;
+      };
+      clientId: {
+        type: "string";
+        required: true;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      sessionId: {
+        type: "string";
+        required: false;
+        references: {
+          model: string;
+          field: string;
+          onDelete: "set null";
+        };
+        index: true;
+      };
+      userId: {
+        type: "string";
+        required: false;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      referenceId: {
+        type: "string";
+        required: false;
+      };
+      authorizationCodeId: {
+        type: "string";
+        required: false;
+        index: true;
+      };
+      resources: {
+        type: "string[]";
+        required: false;
+      };
+      requestedUserInfoClaims: {
+        type: "string[]";
+        required: false;
+      };
+      refreshId: {
+        type: "string";
+        required: false;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      expiresAt: {
+        type: "date";
+      };
+      createdAt: {
+        type: "date";
+      };
+      revoked: {
+        type: "date";
+        required: false;
+      };
+      confirmation: {
+        type: "json";
+        required: false;
+      };
+      scopes: {
+        type: "string[]";
+        required: true;
+      };
+    };
+  };
+  oauthConsent: {
+    modelName: string;
+    fields: {
+      clientId: {
+        type: "string";
+        required: true;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      userId: {
+        type: "string";
+        required: false;
+        references: {
+          model: string;
+          field: string;
+        };
+        index: true;
+      };
+      referenceId: {
+        type: "string";
+        required: false;
+      };
+      resources: {
+        type: "string[]";
+        required: false;
+      };
+      requestedUserInfoClaims: {
+        type: "string[]";
+        required: false;
+      };
+      scopes: {
+        type: "string[]";
+        required: true;
+      };
+      createdAt: {
+        type: "date";
+      };
+      updatedAt: {
+        type: "date";
+      };
+    };
+  };
+  /**
+   * Single-use record for `private_key_jwt` client assertion `jti` values. The
+   * row id is a digest of the per-client assertion identifier, so a replayed or
+   * concurrent assertion collides on the primary key and the insert fails
+   * atomically on every adapter (SQL primary key, MongoDB `_id`), including
+   * across multiple server processes.
+   *
+   * A row keeps blocking its id until deleted; `expiresAt` marks when removal
+   * is safe, since the assertion it guards has expired and is rejected earlier.
+   * TODO: no scheduled job prunes expired rows yet; like the verification
+   * table, they accumulate until a deployment-level sweep removes them.
+   */
+  oauthClientAssertion: {
+    modelName: string;
+    fields: {
+      expiresAt: {
+        type: "date";
+        required: true;
+      };
+    };
+  };
+};
+//#endregion
+//#region src/types/helpers.d.ts
+type Awaitable<T> = Promise<T> | T;
+//#endregion
+//#region src/types/zod.d.ts
+/**
+ * Validates an RFC 8707 resource indicator. The value must be an absolute URI
+ * with no fragment (RFC 8707 §2). Unlike a redirect URI it is not restricted to
+ * HTTPS, because a resource server identifier may use any absolute URI scheme;
+ * configured OAuth resources are the authoritative control over
+ * which resources a token may target.
+ */
+declare const ResourceUriSchema: z.ZodString;
+/**
+ * Request body accepted at `POST /oauth2/register` (RFC 7591 §2 client
+ * metadata). This is the single source of truth for the registration contract:
+ * the endpoint validates against it and {@link ClientRegistrationRequest} is
+ * inferred from it, so the type a `validateInitialAccessToken` callback receives
+ * always matches what is actually validated. `grant_types` and
+ * `token_endpoint_auth_method` are open strings because extensions can register
+ * custom values. Server-assigned fields (`client_id`, `client_secret`, the
+ * issued/expiry timestamps) and internal state (`disabled`, `reference_id`) are
+ * never part of a registration request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7591#section-2
+ */
+declare const clientRegistrationRequestSchema: z.ZodObject<{
+  redirect_uris: z.ZodOptional<z.ZodArray<z.ZodURL>>;
+  scope: z.ZodOptional<z.ZodString>;
+  client_name: z.ZodOptional<z.ZodString>;
+  client_uri: z.ZodOptional<z.ZodString>;
+  logo_uri: z.ZodOptional<z.ZodString>;
+  contacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  tos_uri: z.ZodOptional<z.ZodString>;
+  policy_uri: z.ZodOptional<z.ZodString>;
+  software_id: z.ZodOptional<z.ZodString>;
+  software_version: z.ZodOptional<z.ZodString>;
+  software_statement: z.ZodOptional<z.ZodString>;
+  post_logout_redirect_uris: z.ZodOptional<z.ZodArray<z.ZodURL>>;
+  backchannel_logout_uri: z.ZodOptional<z.ZodURL>;
+  backchannel_logout_session_required: z.ZodOptional<z.ZodBoolean>;
+  token_endpoint_auth_method: z.ZodOptional<z.ZodString>;
+  jwks: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>, z.ZodObject<{
+    keys: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  }, z.core.$strip>]>>;
+  jwks_uri: z.ZodOptional<z.ZodString>;
+  grant_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  response_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    code: "code";
+  }>>>;
+  type: z.ZodOptional<z.ZodEnum<{
+    web: "web";
+    native: "native";
+    "user-agent-based": "user-agent-based";
+  }>>;
+  subject_type: z.ZodOptional<z.ZodEnum<{
+    public: "public";
+    pairwise: "pairwise";
+  }>>;
+  dpop_bound_access_tokens: z.ZodOptional<z.ZodBoolean>;
+  resources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  skip_consent: z.ZodOptional<z.ZodNever>;
+}, z.core.$strip>;
+/**
+ * Client metadata as submitted in an RFC 7591 §2 registration request, inferred
+ * from {@link clientRegistrationRequestSchema}. Every value is self-asserted by
+ * the caller (RFC 7591 §5) and is the raw request before registration defaults
+ * are applied, so a `validateInitialAccessToken` callback should treat it as
+ * untrusted and not assume defaulted fields are present.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc7591#section-2
+ */
+type ClientRegistrationRequest = z.infer<typeof clientRegistrationRequestSchema>;
+//#endregion
+//#region src/types/index.d.ts
+type StoreTokenType = "access_token" | "refresh_token" | "authorization_code" | (string & {});
+type InternallySupportedScopes = "openid" | "profile" | "email" | "offline_access";
+type Scope = LiteralString | InternallySupportedScopes;
+type Prompt = "none" | "consent" | "login" | "create" | "select_account";
+type AuthorizePrompt = Prompt | "login consent" | "select_account consent";
+/**
+ * Describes how to resolve a `client_id` from an external source (a URL-based
+ * metadata document, a federated registry, an attestation header, etc.) and
+ * what fields that source contributes to discovery metadata.
+ *
+ * Plugins contribute one of these through
+ * {@link OAuthProviderExtension.clientDiscovery}. The host walks every
+ * configured entry in order and returns the first non-null `resolve()` result.
+ */
+interface ClientDiscovery {
+  /**
+   * Stable identifier used in error messages and diagnostics. Convention
+   * is to match the plugin id (for example `"cimd"`).
+   */
+  readonly id: string;
+  /**
+   * Return `true` if this discovery handles the given `client_id`. Called
+   * on every `getClient()` lookup for every configured discovery, so keep
+   * it cheap and synchronous.
+   */
+  matches: (clientId: string) => boolean;
+  /**
+   * Resolve a client when this discovery matches. Receives the existing DB
+   * record (or `null`) so an implementation can decide between creating,
+   * refreshing, or passing through to the database result.
+   *
+   * Return:
+   * - a client record: `getClient()` returns it (creation / refresh / takeover).
+   * - `null`: `getClient()` falls through to the next matching discovery
+   *   or to the database record (if any).
+   */
+  resolve: (ctx: GenericEndpointContext, clientId: string, existing: SchemaClient<Scope[]> | null) => Awaitable<SchemaClient<Scope[]> | null>;
+  /**
+   * Fields merged into `/.well-known/oauth-authorization-server` and
+   * `/.well-known/openid-configuration` responses. Useful for advertising
+   * RFC-registered discovery flags like
+   * `client_id_metadata_document_supported`.
+   */
+  discoveryMetadata?: Record<string, unknown>;
+}
+interface OAuthAuthenticatedClient {
+  clientId: string;
+  client: SchemaClient<Scope[]>;
+  method?: TokenEndpointAuthMethod;
+  /**
+   * A sender-constraint the authentication step already proved (for example a
+   * wallet-instance key thumbprint). Pass it to `issueTokens` as
+   * {@link OAuthTokenIssueParams.confirmation} to bind the issued token to it.
+   * The authorization server writes this as token material and does not verify
+   * it again, so a strategy must set it only after proving possession.
+   */
+  confirmation?: Confirmation;
+}
+interface OAuthClientAuthenticationRequest {
+  /**
+   * Scopes to validate against the registered client.
+   */
+  scopes?: string[];
+  /**
+   * Set to `false` for public extension grants that only require client_id.
+   *
+   * @default true
+   */
+  requireCredentials?: boolean;
+}
+interface OAuthTokenIssueParams {
+  client: SchemaClient<Scope[]>;
+  scopes: string[];
+  user?: User;
+  referenceId?: string;
+  sessionId?: string;
+  nonce?: string;
+  refreshToken?: OAuthRefreshToken<Scope[]> & {
+    id: string;
+  };
+  authTime?: Date;
+  verificationValue?: VerificationValue;
+  resources?: string[];
+  /** Full original authorized resources for the grant, used to seed refresh tokens. */
+  originalResources?: string[];
+  /**
+   * OIDC UserInfo claim names requested by the authorization request's
+   * `claims.userinfo` object. The authorization server persists these names so
+   * refresh-token rotation and opaque access tokens continue honoring the same
+   * UserInfo request contract.
+   */
+  requestedUserInfoClaims?: string[];
+  /**
+   * Additional JWT access-token claims for this single issuance.
+   *
+   * JWT-only: these are baked into the signed token at mint. Opaque access
+   * tokens persist no per-issuance claims, so they do NOT reappear at
+   * introspection. A claim that must be visible at opaque-token introspection
+   * belongs in a grant-type-stable `claims.accessToken` contributor instead,
+   * which the introspection path re-derives. Reserved RFC 9068 claim names stay
+   * owned by the authorization server.
+   */
+  accessTokenClaims?: Record<string, unknown>;
+  /**
+   * Additional ID-token claims for this single issuance. Additive: they cannot
+   * replace identity, authentication-context, or AS-owned claims.
+   */
+  idTokenClaims?: Record<string, unknown>;
+  /**
+   * Additional fields for the token response envelope. Standard OAuth token
+   * response fields stay owned by the authorization server.
+   */
+  tokenResponse?: Record<string, unknown>;
+  /**
+   * Sender-constraint to bind this issuance to (RFC 7800 `cnf`). When set, the
+   * issuer stamps it as the access token's `cnf` and derives `token_type` from
+   * it, instead of leaving the token a bearer token. Use it to carry a
+   * confirmation a client-auth strategy or an out-of-band flow already proved
+   * (see {@link OAuthAuthenticatedClient.confirmation}). `cnf` is AS-owned: it
+   * is stamped after, and cannot be overridden by, contributed claims.
+   */
+  confirmation?: Confirmation;
+}
+interface OAuthTokenResponse {
+  access_token: string;
+  expires_in: number;
+  expires_at: number;
+  token_type: TokenType;
+  refresh_token: string | undefined;
+  scope: string;
+  id_token: string | undefined;
+  [key: string]: unknown;
+}
+type ActiveAccessTokenPayload = JWTPayload & {
+  active: true;
+};
+/**
+ * The OAuth Provider's server-side capability surface, bound to a request `ctx`.
+ * A grant handler receives one as `provider`; a companion plugin's own endpoint
+ * obtains one with `getOAuthProviderApi(ctx, opts, grantType?)`. The same object
+ * serves both, so issuance, client resolution, and token verification behave the
+ * same inside and outside a grant.
+ */
+interface OAuthProviderApi {
+  /**
+   * Resolves a registered client by id, consulting extension client-discovery
+   * sources. Returns `null` when no client matches.
+   */
+  getClient: (clientId: string) => Awaitable<SchemaClient<Scope[]> | null>;
+  /**
+   * Authenticates the calling client from the request (client secret, assertion,
+   * or none). For assertion-based methods, the RFC 7523 audience is bound to the
+   * endpoint serving the request, so an assertion cannot be replayed across
+   * endpoints. Returns the authenticated client, plus any `confirmation` an
+   * assertion strategy proved.
+   */
+  authenticateClient: (request?: OAuthClientAuthenticationRequest) => Awaitable<OAuthAuthenticatedClient>;
+  /**
+   * Issues the token set for this grant (access token, optional refresh token,
+   * optional ID token, resource policy, response envelope, and any
+   * sender-constraint). The grant type is fixed by the `getOAuthProviderApi`
+   * binding (the dispatcher's grant for an in-grant handler, the caller's grant
+   * for an out-of-grant endpoint), so it cannot be mislabeled per issuance.
+   *
+   * Authorization is the caller's responsibility. The authorization server does
+   * NOT re-check that `params.scopes`, `params.user`, or `params.resources` are
+   * a subset of what `authenticateClient` validated: this is a raw minting
+   * primitive, and the built-in grants each validate scopes themselves before
+   * calling it.
+   */
+  issueTokens: (params: OAuthTokenIssueParams) => Awaitable<OAuthTokenResponse>;
+  /**
+   * Computes the stored lookup key for a token value (the same hash the
+   * provider persists), so a caller can find or revoke a previously issued
+   * opaque token by its value.
+   */
+  hashToken: (token: string, type: StoreTokenType) => Awaitable<string>;
+  /**
+   * Validates an access token for introspection-style callers. The returned
+   * payload can be inactive; protected-resource endpoints should use
+   * `requireActiveAccessToken`.
+   */
+  validateAccessToken: (token: string, clientId?: string) => Awaitable<JWTPayload>;
+  /**
+   * Validates an access token for a protected resource and throws the OAuth
+   * bearer challenge when the token is inactive or unknown.
+   */
+  requireActiveAccessToken: (token: string, clientId?: string) => Awaitable<ActiveAccessTokenPayload>;
+}
+interface OAuthExtensionGrantHandlerInput {
+  ctx: GenericEndpointContext;
+  opts: OAuthOptions<Scope[]>;
+  grantType: GrantType;
+  /** The provider capability surface, pre-bound to this grant's `grantType`. */
+  provider: OAuthProviderApi;
+}
+type OAuthExtensionGrantHandler = (input: OAuthExtensionGrantHandlerInput) => Awaitable<OAuthTokenResponse>;
+interface OAuthClientAuthenticationInput {
+  ctx: GenericEndpointContext;
+  opts: OAuthOptions<Scope[]>;
+  assertion: string;
+  assertionType: string;
+  clientId?: string;
+  /**
+   * The endpoint URL the assertion was presented to. A strategy MUST bind the
+   * assertion to this audience (see {@link OAuthClientAuthenticationStrategy.authenticate}).
+   */
+  expectedAudience?: string;
+}
+interface OAuthClientAuthenticationResult {
+  /** The client id the assertion proved the caller controls. */
+  clientId: string;
+  /**
+   * A sender-constraint the strategy proved (for example a wallet-instance key
+   * thumbprint). The provider stamps it as the issued token's RFC 7800 `cnf`.
+   * Set it only after proving possession; the authorization server writes it as
+   * token material and does not verify it again.
+   */
+  confirmation?: Confirmation;
+}
+interface OAuthClientAuthenticationStrategy {
+  /**
+   * Assertion type URIs this strategy consumes from `client_assertion_type`.
+   * Values must be absolute URIs per RFC 7521. When omitted, the strategy key
+   * in `OAuthProviderExtension.clientAuthentication` is used and must also be
+   * an absolute URI.
+   */
+  assertionTypes?: string[];
+  /**
+   * Verifies the presented assertion and returns the proven client id (plus any
+   * sender-constraint it established). The strategy proves the caller controls
+   * `clientId`; it does not supply the authorization record. The provider
+   * resolves and authorizes the client itself, so a strategy cannot influence
+   * the client's grants, scopes, or enabled state.
+   *
+   * The strategy owns the full RFC 7521/7523 verification. After verifying the
+   * signature against its own key source, it MUST enforce the assertion-hygiene
+   * checks the built-in `private_key_jwt` path enforces, or the provider will
+   * accept a forged or replayed assertion:
+   * - bind the assertion to `input.expectedAudience` (RFC 7523 §3 rule 3),
+   * - require a bounded `exp` (RFC 7523 §3 rule 4),
+   * - reject replays via a single-use `jti`.
+   *
+   * The exported `consumeClientAssertion` helper performs the audience,
+   * lifetime, and `jti` single-use checks for a decoded payload; call it after
+   * signature verification so an extension method inherits the same guarantees
+   * as `private_key_jwt`.
+   */
+  authenticate: (input: OAuthClientAuthenticationInput) => Awaitable<OAuthClientAuthenticationResult>;
+}
+interface OAuthMetadataExtensionInput {
+  ctx: GenericEndpointContext;
+  opts: OAuthOptions<Scope[]>;
+  type: "oauth-authorization-server" | "openid-configuration";
+  /**
+   * The discovery document the provider assembled (core authorization-server
+   * fields plus any client-discovery metadata). Contributions from other
+   * extensions are merged afterwards and are not reflected here, so a
+   * contributor decides what to add from provider state alone, independent of
+   * extension registration order. The contributor returns the fields to add.
+   */
+  document: AuthServerMetadata | OIDCMetadata;
+}
+interface OAuthClaimExtensionInput {
+  ctx: GenericEndpointContext;
+  opts: OAuthOptions<Scope[]>;
+  user?: (User & Record<string, unknown>) | null;
+  client: SchemaClient<Scope[]>;
+  scopes: string[];
+  grantType?: GrantType;
+  referenceId?: string;
+  /**
+   * Session the tokens are issued for, when one is available. Best-effort:
+   * set on the session-backed grants (authorization_code, refresh_token),
+   * undefined otherwise (client_credentials, introspection, or a session that
+   * was deleted or unlinked). Treat as possibly undefined.
+   */
+  sessionId?: string;
+  resources?: string[];
+  /** Parsed client metadata, as returned by `parseClientMetadata`. */
+  metadata?: Record<string, unknown>;
+}
+interface OAuthUserInfoExtensionInput {
+  ctx: GenericEndpointContext;
+  opts: OAuthOptions<Scope[]>;
+  user: User & Record<string, unknown>;
+  scopes: string[];
+  jwt: JWTPayload;
+  client?: SchemaClient<Scope[]>;
+  /**
+   * Claim names explicitly requested through the OIDC `claims.userinfo`
+   * authorization request parameter.
+   */
+  requestedClaims: string[];
+}
+/**
+ * What a companion plugin contributes to the OAuth Provider, registered through
+ * `extendOAuthProvider(ctx, extension)` (or the `oauthProvider({ extensions })`
+ * option).
+ *
+ * All five kinds live on one object so a single protocol plugin (for example
+ * RFC 8693 token exchange, which adds a grant, advertises metadata, and emits
+ * claims) registers atomically and the host validates the combined surface in
+ * one place. Every field is independently optional, so a single-concern plugin
+ * (such as `@better-auth/cimd`, which contributes only `clientDiscovery`) sets
+ * just the one it needs. This is the shape every future OAuth RFC plugin copies.
+ *
+ * Two contribution disciplines:
+ * - Dispatched kinds (`grants`, `clientAuthentication`) must be disjoint across
+ *   extensions: registering a grant type, auth method, or assertion type that
+ *   another extension already registered is rejected at setup, since the second
+ *   would otherwise be silently unreachable.
+ * - Additive kinds (`metadata`, `claims`) never override authorization-server
+ *   core; a key already owned by the provider is kept, and a key two extensions
+ *   both contribute resolves to the first-registered extension.
+ */
+interface OAuthProviderExtension {
+  /**
+   * Token grants keyed by absolute-URI `grant_type`. The token endpoint
+   * dispatches a matching `grant_type` to the handler, which authenticates the
+   * client and issues tokens through the shared `provider`.
+   */
+  grants?: Record<string, OAuthExtensionGrantHandler>;
+  /**
+   * Assertion-based client authentication, keyed by the advertised
+   * `token_endpoint_auth_method`. Consumes the matching `client_assertion_type`
+   * at the token, introspection, and revocation endpoints. Built-in method
+   * names (`client_secret_basic`/`_post`, `private_key_jwt`, `none`) are
+   * reserved.
+   */
+  clientAuthentication?: Record<string, OAuthClientAuthenticationStrategy>;
+  /**
+   * Additional discovery metadata fields. Core fields (`issuer`,
+   * `token_endpoint`, advertised grants and auth methods, ...) stay owned by
+   * the provider; only absent keys are added. To advertise the claim names a
+   * claims contributor emits, set `advertisedMetadata.claims_supported`: the
+   * provider owns `claims_supported` and does not infer it from contributors.
+   */
+  metadata?: (input: OAuthMetadataExtensionInput) => Record<string, unknown>;
+  /**
+   * Additional claims for access tokens, ID tokens, and the UserInfo response.
+   * Strictly additive: a contributor can add new claims but never replace an
+   * identity, authentication-context, reserved RFC 9068, or other AS-owned
+   * claim. Access-token claims are re-derived at opaque-token introspection, so
+   * they must be grant-type-stable (a contributor receives `grantType:
+   * undefined` there). See the claim-authority overview in the docs for the
+   * full per-token precedence ladder.
+   */
+  claims?: {
+    accessToken?: (input: OAuthClaimExtensionInput) => Awaitable<Record<string, unknown>>;
+    idToken?: (input: OAuthClaimExtensionInput) => Awaitable<Record<string, unknown>>;
+    userInfo?: (input: OAuthUserInfoExtensionInput) => Awaitable<Record<string, unknown>>;
+  };
+  /**
+   * Client-id resolution sources consulted by `getClient()`, plus the
+   * discovery-metadata fields they advertise. Entries across all extensions
+   * run in order; the first to return a client wins. A plugin that resolves
+   * clients from an external source (a metadata-document URL, a federated
+   * registry, an attestation header) contributes it here.
+   */
+  clientDiscovery?: ClientDiscovery | ClientDiscovery[];
+}
+/**
+ * Result of authorizing an RFC 7591 initial access token, returned by
+ * {@link OAuthOptions.validateInitialAccessToken}.
+ */
+interface InitialAccessTokenAuthorization {
+  /**
+   * Ownership reference to attach to the created OAuth client.
+   *
+   * Associates machine-provisioned clients with an organization, team, tenant,
+   * or other application-level owner. Omit to create an unowned client (the
+   * client is stored with neither a `user_id` nor a `reference_id`).
+   */
+  referenceId?: string;
+}
+interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScopes[]> {
+  /**
+   * Custom schema definitions
+   */
+  schema?: InferOptionSchema<typeof schema>;
+  /**
+   * The scopes that the client is allowed to request.
+   * Must contain "openid" to be considered an OIDC server,
+   * otherwise it is just an OAuth server.
+   *
+   * @see https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims
+   * @default
+   * ```ts
+   * ["openid", "profile", "email", "offline_access"]
+   * ```
+   */
+  scopes?: Scopes;
+  /**
+   * Protected resources the AS issues access tokens for. Promotes the
+   * resource model into a first-class persisted entity with per-resource
+   * token policy.
+   *
+   * - String form: each string becomes an `oauthResource` row using plugin-level
+   *   defaults.
+   * - Object form: explicit per-resource policy (TTL, signing alg, scope
+   *   allowlist, custom claims, sender-constraint requirements).
+   *
+   * Seeding is keyed by `identifier`. Behavior on re-seed is controlled by
+   * {@link OAuthOptions.resourceSeedMode}.
+   *
+   * @see RFC 8707 — `identifier` is the `resource` parameter value
+   * @example
+   * ```ts
+   * resources: [
+   *   { identifier: "https://api.example.com/admin", accessTokenTtl: 300,
+   *     allowedScopes: ["admin:read", "admin:write"] },
+   *   "https://api.example.com/public",
+   * ]
+   * ```
+   */
+  resources?: Array<string | OAuthResourceInput>;
+  /**
+   * Controls whether boot-time `resources` config overwrites DB-edited rows.
+   *
+   * - `"insertOnly"` (default, safe): only inserts rows whose `identifier` is
+   *   not already present. Existing rows are untouched — admin edits via CRUD
+   *   are never reverted on restart.
+   * - `"merge"`: inserts missing rows; updates only fields present in the
+   *   config object for existing rows.
+   * - `"overwrite"`: inserts missing rows; replaces existing rows with the
+   *   config values. Use only when the config is the source of truth.
+   *
+   * Defaults to the safe option to prevent accidental policy reverts in
+   * production deployments.
+   *
+   * @default "insertOnly"
+   */
+  resourceSeedMode?: "insertOnly" | "merge" | "overwrite";
+  /**
+   * Opt-in cache membership for resources by `identifier`. Mirrors the
+   * {@link OAuthOptions.cachedTrustedClients} pattern.
+   *
+   * Cached resources are invalidated on every CRUD write. Resources not in
+   * this set are looked up from the DB on every request — the safe default
+   * when admins edit rows through external tooling.
+   */
+  cachedResources?: Set<string>;
+  /**
+   * When true, `/oauth2/token` and `/oauth2/authorize` require the client to be
+   * linked to every requested resource via `oauthClientResource`. When false,
+   * clients implicitly have access to all enabled resources.
+   *
+   * Defaults to `true`, enabling per-client validation per RFC 8707 §3. An
+   * explicit `false` keeps all enabled resources requestable by any client.
+   *
+   * The resolved value is logged at plugin init so admins see which default
+   * applied.
+   */
+  enforcePerClientResources?: boolean;
+  /**
+   * Customize how a resource `identifier` is validated when resources are
+   * created via CRUD or DCR. The default rejects non-URI identifiers per
+   * RFC 8707 §2 (absolute URI, no fragment). Override only for trusted
+   * internal use cases.
+   *
+   * @default RFC 8707 strict URI validator
+   */
+  identifierValidator?: (identifier: string) => Awaitable<boolean>;
+  /**
+   * RBAC on OAuth resources. Mirrors {@link OAuthOptions.clientPrivileges}.
+   *
+   * Gates the admin resource CRUD endpoints. Return `false` (or `undefined`)
+   * to deny the action.
+   */
+  resourcePrivileges?: (context: {
+    headers: Headers;
+    action: "create" | "read" | "update" | "delete" | "list" | "link" | "unlink";
+    user?: User & Record<string, unknown>;
+    session?: Session & Record<string, unknown>;
+    resourceId?: string;
+  }) => Awaitable<boolean | undefined>;
+  /**
+   * Automatically cache trusted clients by client_id.
+   * Clients are cached at request.
+   *
+   * Additionally, cached trusted clients are immutable
+   * through the CRUD endpoints.
+   */
+  cachedTrustedClients?: Set<string>;
+  /**
+   * The amount of time in seconds that the access token is valid for.
+   *
+   * @default 3600 (1 hour) - Industry standard
+   */
+  accessTokenExpiresIn?: number;
+  /**
+   * The amount of time in seconds that a client
+   * credentials grant access token is valid for.
+   *
+   * @default 3600 (1 hour)
+   */
+  m2mAccessTokenExpiresIn?: number;
+  /**
+   * The amount of time in seconds that id token is valid for.
+   *
+   * @default 36000 (10 hours) - Recommended by the OIDC spec
+   */
+  idTokenExpiresIn?: number;
+  /**
+   * The amount of time in seconds that the refresh token is valid for.
+   * Typical industry standard is 30 days
+   *
+   * @default 2592000 (30 days)
+   */
+  refreshTokenExpiresIn?: number;
+  /**
+   * Seconds that a rotated refresh token can be reused to receive the same
+   * token response for the same effective scopes, requested resources, and
+   * sender constraint.
+   *
+   * Matching reuse inside this interval is treated as refresh-response replay,
+   * not refresh-token replay. Set to `0` to treat any rotated refresh token
+   * reuse as replay.
+   *
+   * @default 0
+   */
+  refreshTokenReuseInterval?: number;
+  /**
+   * The amount of time in seconds that the authorization code is valid for.
+   *
+   * @default 600 (10 minutes) - Recommended by the OIDC spec
+   */
+  codeExpiresIn?: number;
+  /**
+   * Create access token expirations based on scope.
+   *
+   * This is useful for higher-privilege scopes that
+   * require shorter expiration times. The earliest
+   * expiration will take precedence. If not specified,
+   * the default will take place.
+   *
+   * Note: values should be lower than the defaults
+   * `accessTokenExpiresIn` and `m2mAccessTokenExpiresIn`
+   *
+   * @example
+   * { "write:payments": "5m", "read:payments": "30m" }
+   */
+  scopeExpirations?: { [K in Scopes[number]]?: number | string | Date };
+  /**
+   * Maximum lifetime in seconds for client assertion JWTs
+   * used with `private_key_jwt` authentication.
+   *
+   * @default 300 (5 minutes)
+   */
+  assertionMaxLifetime?: number;
+  /**
+   * Allows /oauth2/public-client-prelogin endpoint to be
+   * requestable prior to login via a valid oauth_query.
+   */
+  allowPublicClientPrelogin?: boolean;
+  /**
+   * Allow unauthenticated dynamic client registration.
+   *
+   * When enabled, the `/oauth2/register` endpoint accepts requests
+   * without a session. Public clients use
+   * `token_endpoint_auth_method: "none"`; confidential clients receive a
+   * one-time `client_secret` in the registration response.
+   *
+   * For verified client discovery (MCP), consider installing the
+   * `@better-auth/cimd` plugin, which verifies client identity through
+   * domain ownership via Client ID Metadata Documents.
+   *
+   * @default false
+   */
+  allowUnauthenticatedClientRegistration?: boolean;
+  /**
+   * Allow dynamic client registration (RFC 7591) at `POST /oauth2/register`.
+   *
+   * Once enabled, a registration request is authorized through one of three
+   * modes:
+   * - session-backed: a logged-in user with client-create privileges.
+   * - token-backed: a valid initial access token, when
+   *   {@link OAuthOptions.validateInitialAccessToken} is defined.
+   * - open: unauthenticated registration, when
+   *   {@link OAuthOptions.allowUnauthenticatedClientRegistration}
+   *   is enabled.
+   *
+   * @default false
+   */
+  allowDynamicClientRegistration?: boolean;
+  /**
+   * Validates an RFC 7591 initial access token for protected dynamic client
+   * registration, read from the `Authorization: Bearer <token>` header on
+   * `POST /oauth2/register`.
+   *
+   * Return an {@link InitialAccessTokenAuthorization} (optionally carrying a
+   * `referenceId` owner) to authorize the registration, or `false` to reject
+   * the token. Defining this callback enables the token-backed registration
+   * mode; while it is undefined, a Bearer token presented to the endpoint is
+   * rejected rather than downgraded to open registration.
+   *
+   * `clientMetadata` is the schema-validated request body. It is self-asserted
+   * (RFC 7591 §5) and not yet semantically validated, so a request authorized
+   * here may still be rejected by a later metadata check. Compare the token in
+   * constant time; issuance, storage, expiration, and revocation are
+   * deployment-specific in RFC 7591 and belong in your application.
+   *
+   * `headers` is the raw request `Headers`, available to correlate the token
+   * with other request context (a tenant header, a forwarded client identity).
+   *
+   * With the `bearer` plugin enabled, a Bearer value that resolves to a valid
+   * user session is handled as that session, not as an initial access token.
+   *
+   * @see InitialAccessTokenAuthorization
+   */
+  validateInitialAccessToken?: (context: {
+    initialAccessToken: string;
+    headers: Headers;
+    clientMetadata: ClientRegistrationRequest;
+  }) => Awaitable<InitialAccessTokenAuthorization | false>;
+  /**
+   * OAuth/OIDC extension points used by companion plugins to add protocol
+   * grants, client authentication methods, metadata, claims, and client-id
+   * discovery without modifying oauth-provider core for each RFC.
+   *
+   * Extension plugins should prefer `extendOAuthProvider(ctx, extension)` in
+   * their `init()` hook so users can compose plugins declaratively. Plugins
+   * such as `@better-auth/cimd` contribute their client discovery this way.
+   */
+  extensions?: OAuthProviderExtension[];
+  /**
+   * List of scopes for newly registered clients
+   * if not requested.
+   *
+   * For scopes that shall automatically adapt to your scopes
+   * list in the future (ie scopes: undefined), create that client
+   * using the server's `createOAuthClient` function.
+   *
+   * @default scopes
+   */
+  clientRegistrationDefaultScopes?: Scopes;
+  /**
+   * List of scopes for allowed clients in addition to
+   * those listed in the default scope. Finalized allowed list is
+   * the union of the default scopes and this list.
+   *
+   * If both clientRegistrationDefaultScopes and this
+   * are undefined, only scopes listed in the scopes option
+   * are allowed.
+   *
+   * @default - clientRegistrationDefaultScopes
+   */
+  clientRegistrationAllowedScopes?: Scopes;
+  /**
+   * Whether dynamically registered confidential clients require PKCE by default.
+   *
+   * This is server-owned registration policy. Dynamic client registration does
+   * not accept `require_pkce` from the client request, and public clients or
+   * authorization requests with `offline_access` still require PKCE unless the
+   * confidential OIDC request includes both `openid` and `nonce`.
+   *
+   * @default true
+   */
+  clientRegistrationRequirePKCE?: boolean;
+  /**
+   * How long a dynamically created confidential client
+   * should last for.
+   *
+   * - If a `number` is passed as an argument it is used as the claim directly.
+   * - If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+   *   claim.
+   * - If a `string` is passed as an argument it is resolved to a time span, and then added to the
+   *   current unix timestamp and used as the claim.
+   *
+   * Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+   * day".
+   *
+   * Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+   * "m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+   * "years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+   * alias for a year.
+   *
+   * If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+   * subtracted from the current unix timestamp. A "from now" suffix can also be used for
+   * readability when adding to the current unix timestamp.
+   *
+   * @default - undefined (does not expire)
+   */
+  clientRegistrationClientSecretExpiration?: number | string | Date;
+  /**
+   * Returns the reference id which owns the oauth clients.
+   *
+   * For example, it can be an organization, team, etc.
+   * When provided, user_id of the client will be undefined
+   * and the owner is defined under the field `reference_id`.
+   *
+   * With the organization plugin: @example ({ session }) => {
+   * 	return session?.activeOrganizationId;
+   * }
+   */
+  clientReference?: (context: {
+    user?: User & Record<string, unknown>;
+    session?: Session & Record<string, unknown>;
+  }) => Awaitable<string | undefined>;
+  /**
+   * RBAC on OAuth Clients.
+   *
+   * Provides context to help determine if a user can perform
+   * a specific action.
+   */
+  clientPrivileges?: (context: {
+    headers: Headers;
+    action: "create" | "read" | "update" | "delete" | "list" | "rotate";
+    user?: User & Record<string, unknown>;
+    session?: Session & Record<string, unknown>;
+  }) => Awaitable<boolean | undefined>;
+  /**
+   * List default scopes when using the token endpoint's
+   * grant type "client_credentials". This is used
+   * only when oauthClients are stored in the database
+   * without a scope and you do not want all `scopes` to be given.
+   *
+   * @default undefined
+   */
+  clientCredentialGrantDefaultScopes?: Scopes;
+  /**
+   * Grant types supported by the token endpoint
+   *
+   * @default
+   * ["authorization_code", "client_credentials", "refresh_token"]
+   */
+  grantTypes?: GrantType[];
+  /**
+   * The URL to the login page. This is used if the client requests the `login`
+   * prompt.
+   */
+  loginPage: string;
+  /**
+   * A URL to the consent page where the user will be redirected if the client
+   * requests consent.
+   *
+   * After the user consents, they should be redirected by the client to the
+   * `redirect_uri` with the authorization code.
+   *
+   * When the server redirects the user to the consent page, it will include the
+   * following query parameters:
+   *
+   * - `client_id` - The ID of the client.
+   * - `scope` - The requested scopes.
+   * - `claims` - The OIDC claims request, when the client requested specific
+   *   claims. Consent pages should surface `claims.userinfo` names alongside
+   *   scopes because accepted UserInfo claims can affect the UserInfo response.
+   * - `code` - The authorization code.
+   *
+   * once the user consents, you need to call the `/oauth2/consent` endpoint
+   * with the code and `accept: true` to complete the authorization. Include a
+   * `claims` object if the user accepted only some requested UserInfo claims.
+   * The endpoint will then return the client to the `redirect_uri` with the
+   * authorization code.
+   *
+   * @example
+   * ```ts
+   * consentPage: "/consent"
+   * ```
+   */
+  consentPage: string;
+  /**
+   * Sign Up page settings associated with `prompt: "create"`
+   * @see https://openid.net/specs/openid-connect-prompt-create-1_0.html
+   */
+  signup?: {
+    /**
+     * A URL to the Sign Up page where the user will be redirected
+     * to continue a signup flow.
+     *
+     * Upon completion of signup, you need to call the `/oauth2/continue`
+     * with `created: true` to continue the login flow.
+     *
+     * @default loginPage
+     * @example `/sign-up`
+     */
+    page?: string;
+    /**
+     * To add registration steps, specify the page(s) to redirect to.
+     *
+     * Note: the account would need to be logged in (or selected)
+     * to specify steps.
+     *
+     * If true, user with redirect to `page`.
+     * If string, user with redirect to the page specified by string.
+     * If false, user has completed registration and will continue auth flow.
+     *
+     * @param context
+     */
+    shouldRedirect?: (context: {
+      headers: Headers;
+      user: User & Record<string, unknown>;
+      session: Session & Record<string, unknown>;
+      scopes: Scopes;
+    }) => Awaitable<boolean | string>;
+  };
+  /**
+   * Select Account page settings associated with `prompt: "select_account"`
+   */
+  selectAccount?: {
+    /**
+     * A URL to the account selection page where the user will be redirected if
+     * the user must select an account (eg. multi-session).
+     *
+     * Once the user selects an account, you need to call the `/oauth2/continue`
+     * with `selected: true` to continue the login flow.
+     *
+     * @default loginPage
+     */
+    page?: string;
+    /**
+     * Checks to see if an account needs selection
+     * for the `/oauth2/authorize` endpoint.
+     *
+     * @returns
+     * - `true`: account is not selected and needs selection
+     * - `false`: intended user or account already selected
+     */
+    shouldRedirect: (context: {
+      headers: Headers;
+      user: User & Record<string, unknown>;
+      session: Session & Record<string, unknown>;
+      scopes: Scopes;
+    }) => Awaitable<boolean>;
+  };
+  /**
+   * Post login page settings
+   */
+  postLogin?: {
+    /**
+     * The page `shouldRedirect` should redirect to.
+     */
+    page: string;
+    /**
+     * A value to tie to the consent reference_id.
+     *
+     * Note that YOU must fail in this function if the requested
+     * scope doesn't have a reference id and it should.
+     */
+    consentReferenceId: (context: {
+      user: User & Record<string, unknown>;
+      session: Session & Record<string, unknown>;
+      scopes: Scopes;
+    }) => Awaitable<string | undefined>;
+    /**
+     * After login and before consent, request the user to
+     * select an additional choice for `/oauth2/authorize`.
+     * For example, allow selection of an organization or team.
+     *
+     * Upon selection of a specific account, use `/oauth2/continue`
+     * with `postLogin: true` to continue the login flow.
+     *
+     * @returns
+     * - `true`: account is not selected and needs selection
+     * - `false`: intended user or account selected
+     */
+    shouldRedirect: (context: {
+      headers: Headers;
+      user: User & Record<string, unknown>;
+      session: Session & Record<string, unknown>;
+      scopes: Scopes;
+    }) => Awaitable<boolean>;
+  };
+  /**
+   * Format your refresh tokens the returned to oauth clients.
+   * For example with JWE encryption/decryption logic.
+   *
+   * If you changed the format after production deployment,
+   * ensure that the prior version can still be decoded.
+   *
+   * NOTE: `prefix.refreshToken` is internally handled,
+   * so `token` only contains the stored database token.
+   */
+  formatRefreshToken?: {
+    /**
+     * Custom session token format sent to client.
+     */
+    encrypt: (token: string, sessionId?: string) => Awaitable<string>;
+    /**
+     * Decodes the custom session token.
+     *
+     * @returns {string | undefined} sessionId - if returned,
+     * should be same as the one received in `encode`.
+     * There is an added benefit that updates to the session occur
+     * via id instead of token.
+     * @returns {string} token - should be same as the one
+     * received in `encode`
+     */
+    decrypt: (token: string) => Awaitable<{
+      sessionId?: string;
+      token: string;
+    }>;
+  };
+  /**
+   * Store the client secret in your database in a secure way
+   * Note: This will not affect the client secret sent to the user,
+   * it will only affect the client secret stored in your database
+   *
+   * When disableJwtPlugin = false (recommended):
+   * - "hashed" - The client secret is hashed using the `hash` function.
+   * - {
+   * 	hash: (clientSecret: string) => Awaitable<string>,
+   * 	verify?: (clientSecret: string, storedHash: string) => Awaitable<boolean>
+   * } - A function that hashes the client secret.
+   *
+   * When disableJwtPlugin = true:
+   * - "encrypted" - The client secret is encrypted using the `encrypt` function.
+   * - {
+   * 	encrypt: (clientSecret: string) => Awaitable<string>,
+   * 	decrypt: (storedSecret: string) => Awaitable<string>
+   * } - A function that encrypts and decrypts the client secret.
+   *
+   * @default
+   * options.disableJwtPlugin ? "encrypted" : "hashed"
+   */
+  storeClientSecret?: "hashed" | "encrypted" | {
+    hash: (clientSecret: string) => Awaitable<string>;
+    verify?: (clientSecret: string, storedHash: string) => Awaitable<boolean>;
+  } | {
+    encrypt: (clientSecret: string) => Awaitable<string>;
+    decrypt: (storedSecret: string) => Awaitable<string>;
+  };
+  /**
+   * Storage method of opaque access tokens and refresh tokens on your database.
+   *
+   * - "hashed" - The client secret is hashed using the `hash` function.
+   * - {
+   * 	hash: (token: string, type: StoreTokenType) => Awaitable<string>
+   * } - A function that hashes the token
+   *
+   * @default "hashed"
+   */
+  storeTokens?: "hashed" | {
+    hash: (token: string, type: StoreTokenType) => Awaitable<string>;
+  };
+  /**
+   * Custom claims provided at the OIDC `userinfo` endpoint.
+   *
+   * @param info - context that may be useful when creating custom claims
+   * @returns Additional claims for userinfo request
+   */
+  customUserInfoClaims?: (info: {
+    /** The user object */user: User & Record<string, unknown>;
+    /** The scopes from the access token used
+     * in the /userinfo request (matches jwt.scopes) */
+    scopes: Scopes; /** The access token payload used in the /userinfo request */
+    jwt: JWTPayload;
+    /**
+     * Claim names explicitly requested through the OIDC `claims.userinfo`
+     * authorization request parameter.
+     */
+    requestedClaims: string[];
+  }) => Awaitable<Record<string, any>>;
+  /**
+   * Custom claims attached to OIDC id tokens.
+   *
+   * To remain OIDC-compliant, claims should be
+   * namespaced with a URI. For example, a site
+   * example.com should namespace an organization at
+   * https://example.com/organization.
+   *
+   * Reserved ID token claim names (`iss`, `sub`, `aud`, `exp`, `nbf`, `iat`,
+   * `jti`, `nonce`, `sid`, `at_hash`, `c_hash`, `s_hash`, `auth_time`, `acr`,
+   * `amr`, `azp`) are stripped at issuance with a warning log. The
+   * authorization server owns these values.
+   *
+   * @param info - context that may be useful when creating custom claims
+   */
+  customIdTokenClaims?: (info: {
+    /** The user object if token is associated to a user. */user: User & Record<string, unknown>; /** Scopes granted for this token */
+    scopes: Scopes; /** oAuthClient metadata */
+    metadata?: Record<string, any>;
+  }) => Awaitable<Record<string, any>>;
+  /**
+   * Custom claims attached to access tokens.
+   *
+   * Claims are added for both the token and introspect endpoints.
+   *
+   * Use the user and referenceId fields to fetch
+   * for membership roles/permissions to attach for the token.
+   * Note that scopes are those that requested,
+   * permissions are what the the user can actually do which
+   * must be done in this function.
+   *
+   * @param info - context that may be useful when creating custom claims
+   */
+  customAccessTokenClaims?: (info: {
+    /** The user object if token is associated to a user. Null if user doesn't exist. Undefined if user not applicable. */user?: (User & Record<string, unknown>) | null; /** reference of the consent/authorization */
+    referenceId?: string; /** Scopes granted for this token */
+    scopes: Scopes; /** The resources requested. */
+    resources?: string[]; /** oAuthClient metadata */
+    metadata?: Record<string, any>;
+  }) => Awaitable<Record<string, any>>;
+  /**
+   * Custom fields to include in the token response body.
+   *
+   * Unlike `customAccessTokenClaims` (which adds claims inside the JWT payload),
+   * this adds fields to the JSON response envelope alongside `access_token`,
+   * `token_type`, etc. Standard OAuth fields (`access_token`, `token_type`,
+   * `expires_in`, `expires_at`, `refresh_token`, `scope`, `id_token`) cannot
+   * be overridden.
+   *
+   * @param info - context that may be useful when creating custom fields
+   */
+  customTokenResponseFields?: (info: {
+    /** The grant type being processed */grantType: GrantType;
+    /**
+     * The user, if applicable.
+     * Undefined for `client_credentials` (M2M, no user).
+     * Always present for `authorization_code` and `refresh_token`.
+     */
+    user?: (User & Record<string, unknown>) | null; /** Scopes granted for this token */
+    scopes: Scopes; /** oAuthClient metadata */
+    metadata?: Record<string, any>;
+    /**
+     * The authorization code verification value.
+     * Only present for `authorization_code` grant. Contains the original
+     * authorization request parameters (`query`), `referenceId`, `sessionId`, etc.
+     */
+    verificationValue?: VerificationValue;
+  }) => Awaitable<Record<string, unknown>>;
+  /**
+   * Overwrite specific /.well-known/openid-configuration
+   * values so they are not available publically.
+   * This may be important if not all clients need specific scopes.
+   */
+  advertisedMetadata?: {
+    /**
+     * Advertised scopes_supported located at /.well-known/openid-configuration
+     *
+     * All values must be found in the scope field
+     */
+    scopes_supported?: Scopes;
+    /**
+     * Advertised claims_supported located at /.well-known/openid-configuration
+     *
+     * Internally supported claims:
+     * ["sub", "iss", "aud", "exp", "iat", "sid", "scope", "azp"]
+     */
+    claims_supported?: string[];
+  };
+  /**
+   * Attach prefixes to returned token types.
+   * NOTE: The prefix is not stored in the database.
+   *
+   * Useful when also using the [API Key Plugin](../api-key/index.ts)
+   * or Secret Scanners (ie Github Secret Scanning, GitGuardian, Trufflehog).
+   *
+   * We recommend to append an underscore to make it more identifiable.
+   */
+  prefix?: {
+    /**
+     * Prefix on returned opaque access tokens.
+     *
+     * Additionally, we recommend you add the prefix prior to the first deployment
+     * otherwise you must utilize this with `generateOpaqueAccessToken` (storing the full
+     * encoded value on the database).
+     *
+     * @example "domain_at_"
+     * @default undefined
+     */
+    opaqueAccessToken?: string;
+    /**
+     * Prefix on returned refresh tokens.
+     *
+     * Additionally, we recommend you add the prefix prior to the first deployment
+     * otherwise you must utilize this with `generateRefreshToken` (storing the full
+     * encoded value on the database).
+     *
+     * @example "domain_rt_"
+     * @default undefined
+     */
+    refreshToken?: string;
+    /**
+     * Prefix on returned client secrets.
+     *
+     * Additionally, we recommend you add the prefix prior to the first deployment
+     * otherwise you must utilize this with `generateClientSecret` (storing the full
+     * encoded value on the database).
+     *
+     * @example "domain_cs_"
+     * @default undefined
+     */
+    clientSecret?: string;
+  };
+  /**
+   * Custom function to generate a client ID.
+   *
+   * @default
+   * generateRandomString(32, "A-Z", "a-z")
+   */
+  generateClientId?: () => string;
+  /**
+   * Custom function to generate a client secret.
+   *
+   * @default
+   * generateRandomString(32, "A-Z", "a-z")
+   */
+  generateClientSecret?: () => string;
+  /**
+   * Generate a unique access token to save on the database.
+   *
+   * @default
+   * generateRandomString(32, "A-Z", "a-z")
+   */
+  generateOpaqueAccessToken?: () => Awaitable<string>;
+  /**
+   * Generate a unique refresh token to save on the database.
+   *
+   * @default
+   * generateRandomString(32, "A-Z", "a-z")
+   */
+  generateRefreshToken?: () => Awaitable<string>;
+  /**
+   * Confirmations that individually silences specific well-known endpoint
+   * configuration warnings.
+   *
+   * Only set these specific values if you see the error as they
+   * are configuration specific.
+   */
+  silenceWarnings?: {
+    /**
+     * Config warning for `/.well-known/oauth-authorization-server/[issuer-path]`
+     *
+     * @default false
+     */
+    oauthAuthServerConfig?: boolean;
+    /**
+     * Config warning for `[issuer-path]/.well-known/openid-configuration`
+     *
+     * @default false
+     */
+    openidConfig?: boolean;
+  };
+  /**
+   * By default, access and id tokens can be issued and verified
+   * through the JWT plugin.
+   *
+   * You can disable the JWT requirement in which access tokens
+   * will always be opaque and id tokens are always signed
+   * with HS256 using the client secret.
+   *
+   * @default false
+   */
+  disableJwtPlugin?: boolean;
+  /**
+   * Rate limit configuration for OAuth endpoints.
+   *
+   * Each endpoint can be configured with a `window` (in seconds) and `max` requests.
+   * Set to `false` to disable rate limiting for a specific endpoint.
+   *
+   * @default
+   * ```ts
+   * {
+   *   token: { window: 60, max: 20 },
+   *   authorize: { window: 60, max: 30 },
+   *   introspect: { window: 60, max: 100 },
+   *   revoke: { window: 60, max: 30 },
+   *   register: { window: 60, max: 5 },
+   *   userinfo: { window: 60, max: 60 },
+   * }
+   * ```
+   */
+  rateLimit?: {
+    /**
+     * Rate limit for /oauth2/token endpoint
+     * @default { window: 60, max: 20 }
+     */
+    token?: {
+      window: number;
+      max: number;
+    } | false;
+    /**
+     * Rate limit for /oauth2/authorize endpoint
+     * @default { window: 60, max: 30 }
+     */
+    authorize?: {
+      window: number;
+      max: number;
+    } | false;
+    /**
+     * Rate limit for /oauth2/introspect endpoint
+     * @default { window: 60, max: 100 }
+     */
+    introspect?: {
+      window: number;
+      max: number;
+    } | false;
+    /**
+     * Rate limit for /oauth2/revoke endpoint
+     * @default { window: 60, max: 30 }
+     */
+    revoke?: {
+      window: number;
+      max: number;
+    } | false;
+    /**
+     * Rate limit for /oauth2/register endpoint
+     * @default { window: 60, max: 5 }
+     */
+    register?: {
+      window: number;
+      max: number;
+    } | false;
+    /**
+     * Rate limit for /oauth2/userinfo endpoint
+     * @default { window: 60, max: 60 }
+     */
+    userinfo?: {
+      window: number;
+      max: number;
+    } | false;
+  };
+  /**
+   * Secret used to compute pairwise subject identifiers (HMAC-SHA256).
+   * When set, clients with `subject_type: "pairwise"` receive unique,
+   * unlinkable `sub` values per sector identifier.
+   *
+   * @see https://openid.net/specs/openid-connect-core-1_0.html#PairwiseAlg
+   */
+  pairwiseSecret?: string;
+  /**
+   * Resolves a `request_uri` at the authorize endpoint (PAR support).
+   *
+   * When the authorize endpoint receives a `request_uri` parameter, this callback
+   * resolves it to the original authorization parameters. Return null if the URI
+   * is invalid or expired.
+   */
+  requestUriResolver?: (input: {
+    requestUri: string;
+    clientId: string;
+    ctx: GenericEndpointContext;
+  }) => Promise<Record<string, string> | null>;
+  /**
+   * DPoP proof validation settings.
+   *
+   * DPoP is enabled by default when a client or resource asks for DPoP-bound
+   * access tokens. These values tune proof validation without changing that
+   * contract.
+   */
+  dpop?: {
+    /**
+     * Accepted age of a DPoP proof JWT in seconds.
+     *
+     * @default 300
+     */
+    proofMaxAgeSeconds?: number;
+    /**
+     * Supported JWS algorithms for DPoP proof JWTs.
+     *
+     * @default ["EdDSA", "ES256", "ES512", "PS256", "RS256"]
+     */
+    signingAlgorithms?: JWSAlgorithms[];
+  };
+}
+interface OAuthAuthorizationQuery {
+  /**
+   * The response type.
+   * - "code": authorization code flow.
+   * Optional in the query when using request_uri (PAR) — resolved from stored params.
+   */
+  response_type?: "code";
+  /**
+   * OpenID Connect Request Object by value.
+   *
+   * The parameter is parsed so unsupported use can be rejected with
+   * `request_not_supported`; Better Auth does not process Request Objects yet.
+   */
+  request?: string;
+  /**
+   * PAR request_uri. When present, other params are resolved from the stored request.
+   */
+  request_uri?: string;
+  /**
+   * The redirect URI for the client. Must be one of the registered redirect URLs for the client.
+   */
+  redirect_uri: string;
+  /**
+   * The scope of the request. Must be a space-separated list of case sensitive strings.
+   *
+   * - "openid" is required for most requests to obtain user id (ie sub)
+   * - "profile" is required for requests that require user profile information.
+   * - "email" is required for requests that require user email information.
+   * - "offline_access" is required for requests that require a refresh token.
+   */
+  scope?: string;
+  /**
+   * Opaque value used to maintain state between the request and the callback. Typically,
+   * Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the
+   * value of this parameter with a browser cookie.
+   *
+   * Recommended for clients, but optional for the authorization server.
+   *
+   * Note: Better Auth stores the state in a database instead of a cookie. - This is to minimize
+   * the complication with native apps and other clients that may not have access to cookies.
+   */
+  state?: string;
+  /**
+   * The client ID. Must be the ID of a registered client.
+   */
+  client_id: string;
+  /**
+   * The prompt parameter is used to specify the type of user interaction that is required.
+   */
+  prompt?: AuthorizePrompt;
+  /**
+   * The display parameter is used to specify how the authorization server displays the
+   * authentication and consent user interface pages to the end user.
+   */
+  display?: "page" | "popup" | "touch" | "wap";
+  /**
+   * End-User's preferred languages and scripts for the user interface, represented as a
+   * space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. For
+   * instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada,
+   * then French (without a region designation), followed by English (without a region
+   * designation).
+   *
+   * Better Auth does not support this parameter yet. It'll not throw an error if it's provided,
+   *
+   * 🏗️ currently not implemented
+   */
+  ui_locales?: string;
+  /**
+   * The maximum authentication age.
+   *
+   * Specifies the allowable elapsed time in seconds since the last time the End-User was
+   * actively authenticated by the provider. If the elapsed time is greater than this value, the
+   * provider MUST attempt to actively re-authenticate the End-User.
+   *
+   * Note that max_age=0 is equivalent to prompt=login.
+   */
+  max_age?: number;
+  /**
+   * Requested Authentication Context Class Reference values.
+   *
+   * Space-separated string that
+   * specifies the acr values that the Authorization Server is being requested to use for
+   * processing this Authentication Request, with the values appearing in order of preference.
+   * The Authentication Context Class satisfied by the authentication performed is returned as
+   * the acr Claim Value, as specified in Section 2. The acr Claim is requested as a Voluntary
+   * Claim by this parameter.
+   */
+  acr_values?: string;
+  /**
+   * Hint to the Authorization Server about the login identifier the End-User might use to log in
+   * (if necessary). This hint can be used by an RP if it first asks the End-User for their
+   * e-mail address (or other identifier) and then wants to pass that value as a hint to the
+   * discovered authorization service. It is RECOMMENDED that the hint value match the value used
+   * for discovery. This value MAY also be a phone number in the format specified for the
+   * phone_number Claim. The use of this parameter is left to the OP's discretion.
+   */
+  login_hint?: string;
+  /**
+   * ID Token previously issued by the Authorization Server being passed as a hint about the
+   * End-User's current or past authenticated session with the Client.
+   *
+   * 🏗️ currently not implemented
+   */
+  id_token_hint?: string;
+  /**
+   * Code challenge
+   */
+  code_challenge?: string;
+  /**
+   * Code challenge method used
+   */
+  code_challenge_method?: "S256";
+  /**
+   * String value used to associate a Client session with an ID Token, and to mitigate replay
+   * attacks. The value is passed through unmodified from the Authentication Request to the ID Token.
+   * If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the
+   * value of the nonce parameter sent in the Authentication Request. If present in the
+   * Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token
+   * with the Claim Value being the nonce value sent in the Authentication Request.
+   */
+  nonce?: string;
+  /**
+   * OIDC Claims request parameter. In an authorization request it is a
+   * form-encoded JSON string; Request Object resolvers may provide the parsed
+   * object form.
+   *
+   * @see https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter
+   */
+  claims?: string | Record<string, unknown>;
+  /**
+   * RFC 9449 authorization request parameter. When present, the authorization
+   * code is bound to this JWK thumbprint and the token request must present a
+   * matching DPoP proof.
+   */
+  dpop_jkt?: string;
+  /**
+   * Resource parameter as specified by [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)
+   */
+  resource?: string | string[];
+}
+/**
+ * A persisted protected-resource row as stored in `oauthResource`.
+ *
+ * `null` on any policy column means "inherit the plugin-level default at
+ * token issuance time" — admins can later override without re-seeding.
+ */
+interface OAuthResource {
+  /** Auto-generated primary key */
+  id: string;
+  /**
+   * Business key used in the `aud` claim and as the RFC 8707 `resource` value.
+   */
+  identifier: string;
+  /** Human-friendly label for admin UIs */
+  name: string;
+  /** Access token TTL in seconds; null inherits {@link OAuthOptions.accessTokenExpiresIn} */
+  accessTokenTtl?: number | null;
+  /** Refresh token TTL in seconds; null inherits {@link OAuthOptions.refreshTokenExpiresIn} */
+  refreshTokenTtl?: number | null;
+  /** When set, overrides the JWT plugin's getLatestKey() default at signing time. */
+  signingAlgorithm?: JWSAlgorithms | null;
+  signingKeyId?: string | null;
+  /**
+   * When non-null, requested scopes must intersect this set or the request is
+   * rejected with `invalid_scope`.
+   */
+  allowedScopes?: string[] | null;
+  /**
+   * Per-resource claims merged into the access token JWT payload. Reserved
+   * RFC 9068 claim names (`iss`, `sub`, `aud`, `exp`, `iat`, `jti`,
+   * `client_id`, `scope`, `auth_time`, `acr`, `amr`) are stripped at issuance
+   * with a warning log — never silently dropped.
+   */
+  customClaims?: Record<string, unknown> | null;
+  /**
+   * Require newly issued access tokens for this resource to be DPoP-bound.
+   */
+  dpopBoundAccessTokensRequired?: boolean;
+  /**
+   * Disabled → no new issuance for this resource; existing tokens still verify
+   * until natural expiry. Compare to delete, which hard-rejects existing tokens.
+   */
+  disabled: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+  /**
+   * Forward-migration anchor. Lets the runtime branch behavior when claim
+   * emission or validation semantics change in a future PR without forcing
+   * every row to migrate. PR 1 ships with `policyVersion = 1`.
+   */
+  policyVersion: number;
+  /** Open-ended extension data — not yet promoted to columns. */
+  metadata?: Record<string, unknown> | null;
+}
+/**
+ * Plugin-config input for {@link OAuthOptions.resources}. A subset of the
+ * persisted {@link OAuthResource} — only `identifier` is required; the rest
+ * fall back to plugin defaults when omitted.
+ */
+interface OAuthResourceInput {
+  identifier: string;
+  name?: string;
+  accessTokenTtl?: number;
+  refreshTokenTtl?: number;
+  signingAlgorithm?: JWSAlgorithms;
+  signingKeyId?: string;
+  allowedScopes?: string[];
+  customClaims?: Record<string, unknown>;
+  dpopBoundAccessTokensRequired?: boolean;
+  disabled?: boolean;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * A row of `oauthClientResource` linking a client to a resource.
+ *
+ * Authoritative only when {@link OAuthOptions.enforcePerClientResources} is true.
+ */
+interface OAuthClientResource {
+  clientId: string;
+  resourceId: string;
+  metadata?: Record<string, unknown> | null;
+  createdAt: Date;
+}
+/**
+ * The authorization request as persisted alongside a minted code. Identical to
+ * {@link OAuthAuthorizationQuery} except `redirect_uri` is optional: a headless
+ * authorization request (first-party-apps / device-style) carries none, and
+ * RFC 6749 §4.1.3 only binds `redirect_uri` at the token endpoint when the
+ * authorization request included one. Mirrors the runtime
+ * `storedAuthorizationQuerySchema`.
+ */
+interface StoredAuthorizationQuery extends Omit<OAuthAuthorizationQuery, "redirect_uri"> {
+  redirect_uri?: string;
+}
+/**
+ * Stored within the verification.value field
+ * in JSON format.
+ *
+ * It is stored in JSON to prevent
+ * direct searches by field on the db
+ */
+interface VerificationValue {
+  type: "authorization_code";
+  query: StoredAuthorizationQuery;
+  sessionId: string;
+  userId: string;
+  resource?: string[];
+  referenceId?: string;
+  authTime?: number;
+}
+/**
+ * Client registered values as used within the plugin
+ */
+interface SchemaClient<Scopes extends readonly Scope[] = InternallySupportedScopes[]> {
+  /**
+   * Client ID
+   *
+   * size 32
+   *
+   * as described on https://www.rfc-editor.org/rfc/rfc6749.html#section-2.2
+   */
+  clientId: string;
+  /**
+   * Client Secret
+   *
+   * A secret for the client, if required by the authorization server.
+   *
+   * size 32
+   */
+  clientSecret?: string;
+  /** Whether the client is disabled or not. */
+  disabled?: boolean;
+  /**
+   * Restricts scopes allowed for the client.
+   *
+   * If not defined, any scope can be requested.
+   */
+  scopes?: Scopes;
+  /** User who owns this client */
+  userId?: string | null;
+  /** Created time */
+  createdAt?: Date;
+  /** Last updated time */
+  updatedAt?: Date;
+  /** Expires time */
+  expiresAt?: Date;
+  /** The name of the client. */
+  name?: string;
+  /** Linkable uri of the client. */
+  uri?: string;
+  /** The icon of the client. */
+  icon?: string;
+  /** List of contacts for the client. */
+  contacts?: string[];
+  /** Client Terms of Service Uri */
+  tos?: string;
+  /** Client Privacy Policy Uri */
+  policy?: string;
+  softwareId?: string;
+  softwareVersion?: string;
+  softwareStatement?: string;
+  /**
+   * List of registered redirect URLs. Must include the whole URL, including the protocol, port,
+   * and path.
+   *
+   * For example, `https://example.com/auth/callback`
+   */
+  redirectUris?: string[];
+  /**
+   * List of registered post-logout redirect URIs. Used for RP-Initiated Logout.
+   * Must include the whole URL, including the protocol, port, and path.
+   *
+   * For example, `https://example.com/logout/callback`
+   */
+  postLogoutRedirectUris?: string[];
+  /**
+   * RP URL that will receive a signed Logout Token when the end-user's OP
+   * session ends. Registering it is the per-client opt-in for back-channel
+   * logout. Must be absolute, without a fragment, and HTTPS for confidential
+   * clients.
+   *
+   * @see https://openid.net/specs/openid-connect-backchannel-1_0.html#RPMetadata
+   */
+  backchannelLogoutUri?: string;
+  /**
+   * When true, the RP requires the `sid` claim in every Logout Token.
+   * User-scoped (sid-less) logouts are not dispatched to such a client.
+   *
+   * @default false
+   */
+  backchannelLogoutSessionRequired?: boolean;
+  tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+  grantTypes?: GrantType[];
+  responseTypes?: "code"[];
+  /** Client's JSON Web Key Set metadata. Mutually exclusive with `jwksUri`. */
+  jwks?: string;
+  /** URI for the client's JSON Web Key Set. Mutually exclusive with `jwks`. Must be HTTPS. */
+  jwksUri?: string;
+  /**
+   * Indicates whether the client is public or confidential.
+   * If public, refreshing tokens doesn't require
+   * a client_secret. Clients are considered confidential by default.
+   *
+   * Uses `token_endpoint_auth_method` field or `type` field to determine
+   *
+   * Described https://www.rfc-editor.org/rfc/rfc6749.html#section-2.1
+   *
+   * @default undefined
+   */
+  public?: boolean;
+  /**
+   * The client type
+   *
+   * Described https://www.rfc-editor.org/rfc/rfc6749.html#section-2.1
+   *
+   * - web - A web application (confidential client)
+   * - native - A mobile application (public client)
+   * - user-agent-based - A user-agent-based application (public client)
+   */
+  type?: "web" | "native" | "user-agent-based";
+  /**
+   * Whether this client requires PKCE for authorization code flow.
+   *
+   * @default true
+   *
+   * Note: PKCE is always required for public clients and when
+   * requesting offline_access scope, regardless of this setting.
+   */
+  requirePKCE?: boolean;
+  /**
+   * RFC 9449 dynamic client metadata. When true, every token request from this
+   * client must include a valid DPoP proof and receive DPoP-bound tokens.
+   */
+  dpopBoundAccessTokens?: boolean;
+  /** Used to indicate if consent screen can be skipped */
+  skipConsent?: boolean;
+  /** Used to enable client to logout via the `/oauth2/end-session` endpoint */
+  enableEndSession?: boolean;
+  /** Subject identifier type: "public" (default) or "pairwise" */
+  subjectType?: "public" | "pairwise";
+  /** Reference to the owner of this client. Eg. Organization, Team, Profile */
+  referenceId?: string;
+  /**
+   * Additional metadata about the client.
+   */
+  metadata?: string;
+}
+interface OAuthOpaqueAccessToken<Scopes extends readonly Scope[] = InternallySupportedScopes[]> {
+  /**
+   * The opaque access token.
+   */
+  token: string;
+  /**
+   * The client ID of the client that requested the access token.
+   */
+  clientId: string;
+  /**
+   * The session ID the access token is associated with.
+   *
+   * Not available in client credentials grant
+   * where no user session is involved.
+   */
+  sessionId?: string;
+  /**
+   * The user ID the access token is associated with.
+   *
+   * Not available in client credentials grant
+   * where no user is involved.
+   */
+  userId?: string;
+  /**
+   * Reference Id of the consent/authorization.
+   *
+   * Not available in client credentials grant
+   * where no user is involved.
+   */
+  referenceId?: string;
+  /**
+   * Stored authorization-code identifier that produced this token family.
+   * Used to revoke tokens after authorization-code replay is detected.
+   */
+  authorizationCodeId?: string;
+  /**
+   * The refresh token the access token is associated with.
+   *
+   * Not available without the "offline_access" scope
+   */
+  refreshId?: string;
+  /** The expiration date of the access token. */
+  expiresAt: Date;
+  /** The creation date of the access token. */
+  createdAt: Date;
+  /**
+   * When the access token was revoked. Set by session-end dispatch, the
+   * revoke endpoint, and back-channel logout. Introspection and protected
+   * endpoints MUST treat a revoked token as inactive.
+   */
+  revoked?: Date | null;
+  /**
+   * Scope granted for the access token.
+   *
+   * Shall match the refreshId.scopes if refreshId is provided.
+   */
+  scopes: Scopes;
+  /**
+   * Resources allowed for this access token.
+   */
+  resources?: string[];
+  /**
+   * OIDC UserInfo claim names requested by the authorization request's
+   * `claims.userinfo` object.
+   */
+  requestedUserInfoClaims?: string[];
+  /**
+   * RFC 7800 `cnf` confirmation that sender-constrains this access token (for
+   * example DPoP `{ jkt }`). Surfaced as the `cnf` claim at introspection.
+   */
+  confirmation?: Confirmation;
+}
+/**
+ * Refresh Token Database Schema
+ */
+interface OAuthRefreshToken<Scopes extends readonly Scope[] = InternallySupportedScopes[]> {
+  token: string;
+  sessionId?: string;
+  userId: string;
+  referenceId?: string;
+  authorizationCodeId?: string;
+  clientId?: string;
+  expiresAt: Date;
+  createdAt: Date;
+  /**
+   * When this token stopped being active.
+   *
+   * A token can be revoked by /oauth2/revoke or consumed by rotation. Use
+   * `rotatedAt` to distinguish rotation from explicit revocation.
+   */
+  revoked?: Date;
+  /**
+   * When this refresh token was consumed by rotation.
+   */
+  rotatedAt?: Date;
+  /**
+   * Encrypted token endpoint response and request fingerprint to replay during
+   * the configured refresh-token reuse interval.
+   */
+  rotationReplayResponse?: string;
+  /**
+   * When the cached rotation response stops being replayable.
+   */
+  rotationReplayExpiresAt?: Date;
+  /**
+   * The time the user originally authenticated.
+   * Persisted so refreshed ID tokens can include a correct `auth_time` claim.
+   */
+  authTime?: Date;
+  /**
+   * Scopes granted for this refresh token.
+   *
+   * Considered Immutable once granted.
+   */
+  scopes: Scopes;
+  /**
+   * Resources allowed for this refresh token
+   */
+  resources?: string[];
+  /**
+   * OIDC UserInfo claim names requested by the authorization request's
+   * `claims.userinfo` object. Carried forward on rotation.
+   */
+  requestedUserInfoClaims?: string[];
+  /**
+   * RFC 7800 `cnf` confirmation that sender-constrains this refresh-token
+   * family (for example DPoP `{ jkt }`). Carried forward on rotation.
+   */
+  confirmation?: Confirmation;
+}
+/**
+ * Consent Database Schema
+ */
+type OAuthConsent<Scopes extends readonly Scope[] = InternallySupportedScopes[]> = {
+  id: string;
+  clientId: string;
+  userId: string;
+  resources?: string[];
+  referenceId?: string;
+  /**
+   * OIDC UserInfo claim names consented from the authorization request's
+   * `claims.userinfo` object.
+   */
+  requestedUserInfoClaims?: string[];
+  scopes: Scopes;
+  createdAt: Date;
+  updatedAt: Date;
+};
+//#endregion
+//#region src/types/oauth.d.ts
+/**
+ * Supported grant types of the token endpoint
+ */
+type BuiltInGrantType = "authorization_code" | "client_credentials" | "refresh_token";
+type GrantType = BuiltInGrantType | (string & {});
+type BuiltInAuthMethod = "client_secret_basic" | "client_secret_post" | "private_key_jwt";
+type AuthMethod = BuiltInAuthMethod | (string & {});
+type TokenEndpointAuthMethod = AuthMethod | "none";
+type BearerMethodsSupported = "header" | "body";
+/**
+ * RFC 7800 `cnf` (confirmation) members that sender-constrain an access token to
+ * a key the client must prove possession of. Each binding mechanism populates
+ * one member of the same object: DPoP sets `jkt` (RFC 9449 §6), mTLS sets
+ * `x5t#S256` (RFC 8705 §3.1). The authorization server is the sole authority
+ * over this value; it is token material, never a contributed claim.
+ */
+type Confirmation = {
+  jkt: string;
+} | {
+  "x5t#S256": string;
+};
+/**
+ * Token presentation scheme returned in `token_type`. A DPoP-bound token uses
+ * `"DPoP"` (RFC 9449 §5); everything else (including mTLS-bound) uses
+ * `"Bearer"`, since the mTLS constraint lives at the TLS layer.
+ */
+type TokenType = "Bearer" | "DPoP";
+/**
+ * Metadata for authentication servers.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8414#section-2
+ */
+interface AuthServerMetadata {
+  /**
+   * The issuer identifier, this is the URL of the provider and can be used to verify
+   * the `iss` claim in the ID token.
+   *
+   * default: the value set for the issuer in the jwt plugin,
+   * otherwise the base URL of the auth server (e.g. `https://example.com`)
+   */
+  issuer: string;
+  /**
+   * The URL of the authorization endpoint.
+   *
+   * @default `/oauth2/authorize`
+   */
+  authorization_endpoint: string;
+  /**
+   * The URL of the token endpoint.
+   *
+   * @default `/oauth2/token`
+   */
+  token_endpoint: string;
+  /**
+   * The URL of the jwks_uri endpoint.
+   *
+   * For JWKS to work, you must install the `jwt` plugin.
+   *
+   * This value is automatically set to `/jwks` if the `jwt` plugin is installed.
+   *
+   * @default `/jwks`
+   */
+  jwks_uri?: string;
+  /**
+   * The URL of the dynamic client registration endpoint.
+   *
+   * This field is only present when `allowDynamicClientRegistration` is enabled.
+   *
+   * @default `/oauth2/register`
+   */
+  registration_endpoint?: string;
+  /**
+   * Supported scopes.
+   */
+  scopes_supported?: string[];
+  /**
+   * Supported response types. (for /authorize endpoint)
+   */
+  response_types_supported: "code"[];
+  /**
+   * Supported response modes.
+   *
+   * `query`: the authorization code is returned in the query string
+   */
+  response_modes_supported: "query"[];
+  /**
+   * Supported grant types.
+   */
+  grant_types_supported: GrantType[];
+  /**
+   * Supported token endpoint authentication methods.
+   *
+   * @default
+   * ["client_secret_basic", "client_secret_post"]
+   */
+  token_endpoint_auth_methods_supported?: TokenEndpointAuthMethod[];
+  /**
+   * Array containing a list of the JWS signing
+   * algorithms ("alg" values) supported by the token endpoint for
+   * the signature on the JWT used to authenticate the client at the
+   * token endpoint for the "private_key_jwt" and "client_secret_jwt"
+   * authentication methods (see field token_endpoint_auth_methods_supported).
+   */
+  token_endpoint_auth_signing_alg_values_supported?: PrivateKeyJwtSigningAlgorithm[];
+  /**
+   * URL of a page containing human-readable information
+   * that developers might want or need to know when using the
+   * authorization server
+   */
+  service_documentation?: string;
+  /**
+   * Languages and scripts supported for the user interface,
+   * represented as an array of language tag values from BCP 47
+   * [RFC5646](https://datatracker.ietf.org/doc/html/rfc5646)
+   */
+  ui_locales_supported?: string[];
+  /**
+   * URL that the authorization server provides to the
+   * person registering the client to read about the authorization
+   * server's requirements on how the client can use the data provided
+   * by the authorization server.
+   */
+  op_policy_uri?: string;
+  /**
+   * URL that the authorization server provides to the
+   * person registering the client to read about the authorization
+   * server's terms of service.
+   */
+  op_tos_uri?: string;
+  /**
+   * URL of the authorization server's OAuth 2.0 revocation
+   * endpoint [RFC7009](https://datatracker.ietf.org/doc/html/rfc7009)
+   */
+  revocation_endpoint?: string;
+  /**
+   * Array containing a list of client authentication
+   * methods supported by this revocation endpoint
+   *
+   * @default
+   * ["client_secret_basic", "client_secret_post"]
+   */
+  revocation_endpoint_auth_methods_supported?: TokenEndpointAuthMethod[];
+  /**
+   * Array containing a list of the JWS signing
+   * algorithms ("alg" values) supported by the revocation endpoint for
+   * the signature on the JWT used to authenticate the client at the
+   * token endpoint for the "private_key_jwt" and "client_secret_jwt"
+   * authentication methods (see field revocation_endpoint_auth_methods_supported).
+   */
+  revocation_endpoint_auth_signing_alg_values_supported?: PrivateKeyJwtSigningAlgorithm[];
+  /**
+   * URL of the authorization server's OAuth 2.0
+   * introspection endpoint [RFC7662](https://datatracker.ietf.org/doc/html/rfc7662)
+   */
+  introspection_endpoint?: string;
+  /**
+   * Array containing a list of client authentication
+   * methods supported by this introspection endpoint
+   *
+   * @default
+   * ["client_secret_basic", "client_secret_post"]
+   */
+  introspection_endpoint_auth_methods_supported?: TokenEndpointAuthMethod[];
+  /**
+   * Array containing a list of the JWS signing
+   * algorithms ("alg" values) supported by the introspection endpoint
+   * used to authenticate the client at the token endpoint for
+   * the "private_key_jwt" and "client_secret_jwt" authentication methods
+   * (see field introspection_endpoint_auth_methods_supported).
+   */
+  introspection_endpoint_auth_signing_alg_values_supported?: PrivateKeyJwtSigningAlgorithm[];
+  /**
+   * Supported code challenge methods.
+   *
+   * @default ["S256"]
+   */
+  code_challenge_methods_supported: "S256"[];
+  /**
+   * Boolean value specifying whether the authorization server provides
+   * the iss parameter in the authorization response (RFC 9207)
+   *
+   * @see https://datatracker.ietf.org/doc/html/rfc9207
+   * @default true
+   */
+  authorization_response_iss_parameter_supported?: boolean;
+  /**
+   * Whether the authorization server supports discovering clients via
+   * [Client ID Metadata Documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/)
+   * (an HTTPS URL as `client_id`).
+   *
+   * Set at runtime by the `@better-auth/cimd` plugin (or any other
+   * `ClientDiscovery` that contributes this field via
+   * {@link ClientDiscovery.discoveryMetadata}). oauth-provider never sets
+   * it on its own.
+   */
+  client_id_metadata_document_supported?: boolean;
+  /**
+   * Boolean value specifying whether the OP supports back-channel logout,
+   * with true indicating support.
+   *
+   * Registered in the "OAuth Authorization Server Metadata" IANA registry
+   * under OpenID Connect Back-Channel Logout 1.0, so this may appear at both
+   * `.well-known/oauth-authorization-server` and `.well-known/openid-configuration`.
+   *
+   * @default false
+   * @see https://openid.net/specs/openid-connect-backchannel-1_0.html#OPMetadata
+   */
+  backchannel_logout_supported?: boolean;
+  /**
+   * Boolean value specifying whether the OP can pass a `sid` (session ID)
+   * Claim in the Logout Token to identify the RP session with the OP.
+   *
+   * When true, the OP also includes `sid` in ID Tokens it issues.
+   *
+   * @default false
+   * @see https://openid.net/specs/openid-connect-backchannel-1_0.html#OPMetadata
+   */
+  backchannel_logout_session_supported?: boolean;
+  /**
+   * JWS algorithms supported for RFC 9449 DPoP proof JWTs.
+   *
+   * @see https://datatracker.ietf.org/doc/html/rfc9449
+   */
+  dpop_signing_alg_values_supported?: JWSAlgorithms[];
+}
+/**
+ * Metadata returned by the openid-configuration endpoint:
+ * /.well-known/openid-configuration
+ *
+ * NOTE: Url structure is different by appending to the end
+ * of the url instead of the base.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8414#section-5
+ */
+interface OIDCMetadata extends AuthServerMetadata {
+  /**
+   * The URL of the userinfo endpoint.
+   *
+   * @default `/oauth2/userinfo`
+   */
+  userinfo_endpoint: string;
+  /**
+   * Authentication Context Class Reference values supported.
+   *
+   * Better Auth does not advertise this field by default because it does not
+   * currently evaluate requested Authentication Context Class References.
+   *
+   * @default
+   * undefined
+   * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+   */
+  acr_values_supported?: string[];
+  /**
+   * Supported subject types.
+   *
+   * pairwise: the subject identifier is unique to the client
+   * public: the subject identifier is unique to the server
+   *
+   * @see https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes
+   */
+  subject_types_supported: ("public" | "pairwise")[];
+  /**
+   * Supported ID token signing algorithms.
+   *
+   * Automatically uses the same algorithm used in the JWK Plugin.
+   * Support for symmetric algorithms is strictly prohibited
+   * to sharing key vulnerabilities!
+   *
+   * @default
+   * ["EdDSA"]
+   */
+  id_token_signing_alg_values_supported: JWSAlgorithms[];
+  /**
+   * Supported claims.
+   *
+   * @default
+   * ["sub", "iss", "aud", "exp", "nbf", "iat", "jti", "email", "email_verified", "name", "family_name", "given_name", "sid", "scope", "azp"]
+   */
+  claims_supported: string[];
+  /**
+   * Whether the OP supports the OIDC `claims` request parameter.
+   *
+   * @default true
+   * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+   */
+  claims_parameter_supported?: boolean;
+  /**
+   * RP-Initiated Logout Endpoint
+   *
+   * @see https://openid.net/specs/openid-connect-rpinitiated-1_0.html
+   */
+  end_session_endpoint: string;
+  /**
+   * Whether the OP supports OpenID Connect Request Objects by value.
+   *
+   * @default false
+   * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+   */
+  request_parameter_supported?: boolean;
+  /**
+   * Whether the OP supports OpenID Connect Request Objects by reference.
+   *
+   * Discovery defaults this field to true when omitted, so providers that do
+   * not support it should advertise false explicitly.
+   *
+   * @default false
+   * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+   */
+  request_uri_parameter_supported?: boolean;
+  /**
+   * Prompt values supported by this OIDC server
+   *
+   * @see https://openid.net/specs/openid-connect-prompt-create-1_0.html#OpenID.Discovery
+   */
+  prompt_values_supported: Prompt[];
+}
+/**
+ * OAuth 2.0 Dynamic Client Registration Schema
+ *
+ * Current spec is based on OAuth 2.0, but shall use
+ * OAuth 2.1 restrictions.
+ *
+ * https://datatracker.ietf.org/doc/html/rfc7591#section-2
+ */
+interface OAuthClient {
+  client_id: string;
+  client_secret?: string;
+  client_secret_expires_at?: number;
+  scope?: string;
+  user_id?: string | null;
+  client_id_issued_at?: number;
+  client_name?: string;
+  client_uri?: string;
+  logo_uri?: string;
+  contacts?: string[];
+  tos_uri?: string;
+  policy_uri?: string;
+  /** JWK Set — accepts either a bare key array or an RFC 7517 JWKS object `{"keys":[...]}` */
+  jwks?: Record<string, unknown>[] | {
+    keys: Record<string, unknown>[];
+  };
+  jwks_uri?: string;
+  software_id?: string;
+  software_version?: string;
+  software_statement?: string;
+  redirect_uris: string[];
+  post_logout_redirect_uris?: string[];
+  /**
+   * RP URL that the OP POSTs a signed Logout Token to when a session at the OP
+   * ends. The RP uses the token to terminate its own session state for that
+   * user (including any access tokens it has bound to the session).
+   *
+   * @see https://openid.net/specs/openid-connect-backchannel-1_0.html#RPMetadata
+   */
+  backchannel_logout_uri?: string;
+  /**
+   * When true, the RP requires the `sid` Claim in every Logout Token it
+   * receives; the OP will not dispatch user-scoped (sid-less) logouts to it.
+   *
+   * @default false
+   * @see https://openid.net/specs/openid-connect-backchannel-1_0.html#RPMetadata
+   */
+  backchannel_logout_session_required?: boolean;
+  token_endpoint_auth_method?: TokenEndpointAuthMethod;
+  grant_types?: GrantType[];
+  response_types?: "code"[];
+  public?: boolean;
+  type?: "web" | "native" | "user-agent-based";
+  disabled?: boolean;
+  skip_consent?: boolean;
+  enable_end_session?: boolean;
+  /**
+   * Whether this client requires PKCE for authorization code flow.
+   *
+   * @default true
+   *
+   * Note: PKCE is always required for public clients. When requesting
+   * offline_access without PKCE, confidential OIDC clients must send both
+   * `openid` and `nonce`.
+   */
+  require_pkce?: boolean;
+  /**
+   * RFC 9449 dynamic client metadata. When true, token requests from this
+   * client must include a valid DPoP proof and receive DPoP-bound access
+   * tokens.
+   */
+  dpop_bound_access_tokens?: boolean;
+  /**
+   * Subject identifier type for this client.
+   *
+   * @see https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes
+   */
+  subject_type?: "public" | "pairwise";
+  reference_id?: string;
+  [key: string]: unknown;
+}
+/**
+ * Resource metadata server as defined by RFC 9728
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc9728#Terminology
+ */
+interface ResourceServerMetadata {
+  /**
+   * The protected resource's resource identifier,
+   * which is a URL that uses the https scheme and
+   * has no fragment component. It also SHOULD NOT
+   * include a query component, but it may if
+   * necessary.
+   *
+   * This SHOULD match the aud field of your JWT.
+   */
+  resource: string;
+  /**
+   * Each server should pertain to one issuer.
+   *
+   * MCP requires at least one server.
+   *
+   * @default [`${baseUrl}/.well-known/oauth-authorization-server`]
+   */
+  authorization_servers?: string[];
+  jwks_uri?: string;
+  scopes_supported?: string[];
+  bearer_methods_supported?: BearerMethodsSupported[];
+  resource_signing_alg_values_supported?: JWSAlgorithms[];
+  resource_name?: string;
+  resource_documentation?: string;
+  resource_policy_uri?: string;
+  resource_tos_uri?: string;
+  tls_client_certificate_bound_access_tokens?: boolean;
+  authorization_details_types_supported?: string;
+  dpop_signing_alg_values_supported?: JWSAlgorithms[];
+  dpop_bound_access_tokens_required?: boolean;
+}
+//#endregion
+export { OAuthProviderExtension as A, StoreTokenType as B, OAuthConsent as C, OAuthOpaqueAccessToken as D, OAuthMetadataExtensionInput as E, OAuthTokenResponse as F, VerificationValue as H, OAuthUserInfoExtensionInput as I, Prompt as L, OAuthResource as M, OAuthResourceInput as N, OAuthOptions as O, OAuthTokenIssueParams as P, SchemaClient as R, OAuthClientResource as S, OAuthExtensionGrantHandlerInput as T, ClientRegistrationRequest as U, StoredAuthorizationQuery as V, ResourceUriSchema as W, OAuthClaimExtensionInput as _, GrantType as a, OAuthClientAuthenticationResult as b, ResourceServerMetadata as c, ActiveAccessTokenPayload as d, AuthorizePrompt as f, OAuthAuthorizationQuery as g, OAuthAuthenticatedClient as h, Confirmation as i, OAuthRefreshToken as j, OAuthProviderApi as k, TokenEndpointAuthMethod as l, InitialAccessTokenAuthorization as m, AuthServerMetadata as n, OAuthClient as o, ClientDiscovery as p, BearerMethodsSupported as r, OIDCMetadata as s, AuthMethod as t, TokenType as u, OAuthClientAuthenticationInput as v, OAuthExtensionGrantHandler as w, OAuthClientAuthenticationStrategy as x, OAuthClientAuthenticationRequest as y, Scope as z };