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

package/dist/{oauth-CU79t-eG.d.mts → oauth-ScTJEcFV.d.mts}

@@ -1,6 +1,7 @@
-import { AssertionSigningAlgorithm } from "@better-auth/core/oauth2";
-import { JWSAlgorithms } from "better-auth/plugins";
+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";
 
@@ -46,6 +47,7 @@ declare const schema: {
           model: string;
           field: string;
         };
+        index: true;
       };
       createdAt: {
         type: "date";
@@ -99,6 +101,14 @@ declare const schema: {
         type: "string[]";
         required: false;
       };
+      backchannelLogoutUri: {
+        type: "string";
+        required: false;
+      };
+      backchannelLogoutSessionRequired: {
+        type: "boolean";
+        required: false;
+      };
       tokenEndpointAuthMethod: {
         type: "string";
         required: false;
@@ -131,6 +141,11 @@ declare const schema: {
         type: "boolean";
         required: false;
       };
+      dpopBoundAccessTokens: {
+        type: "boolean";
+        required: false;
+        defaultValue: false;
+      };
       referenceId: {
         type: "string";
         required: false;
@@ -141,6 +156,141 @@ declare const schema: {
       };
     };
   };
+  /**
+   * 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"
    *
@@ -151,6 +301,7 @@ declare const schema: {
       token: {
         type: "string";
         required: true;
+        unique: true;
       };
       clientId: {
         type: "string";
@@ -159,6 +310,7 @@ declare const schema: {
           model: string;
           field: string;
         };
+        index: true;
       };
       sessionId: {
         type: "string";
@@ -168,6 +320,7 @@ declare const schema: {
           field: string;
           onDelete: "set null";
         };
+        index: true;
       };
       userId: {
         type: "string";
@@ -176,11 +329,25 @@ declare const schema: {
           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";
       };
@@ -191,10 +358,26 @@ declare const schema: {
         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;
@@ -202,7 +385,7 @@ declare const schema: {
     };
   };
   /**
-   * An opaque access token sent when there is no audience
+   * 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
@@ -227,6 +410,7 @@ declare const schema: {
           model: string;
           field: string;
         };
+        index: true;
       };
       sessionId: {
         type: "string";
@@ -236,6 +420,7 @@ declare const schema: {
           field: string;
           onDelete: "set null";
         };
+        index: true;
       };
       userId: {
         type: "string";
@@ -244,11 +429,25 @@ declare const schema: {
           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;
@@ -256,6 +455,7 @@ declare const schema: {
           model: string;
           field: string;
         };
+        index: true;
       };
       expiresAt: {
         type: "date";
@@ -263,6 +463,14 @@ declare const schema: {
       createdAt: {
         type: "date";
       };
+      revoked: {
+        type: "date";
+        required: false;
+      };
+      confirmation: {
+        type: "json";
+        required: false;
+      };
       scopes: {
         type: "string[]";
         required: true;
@@ -279,6 +487,7 @@ declare const schema: {
           model: string;
           field: string;
         };
+        index: true;
       };
       userId: {
         type: "string";
@@ -287,11 +496,20 @@ declare const schema: {
           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;
@@ -304,13 +522,104 @@ declare const schema: {
       };
     };
   };
+  /**
+   * 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";
+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";
@@ -320,11 +629,11 @@ type AuthorizePrompt = Prompt | "login consent" | "select_account consent";
  * metadata document, a federated registry, an attestation header, etc.) and
  * what fields that source contributes to discovery metadata.
  *
- * Plugins install one of these onto {@link OAuthOptions.clientDiscovery}.
- * The host walks the configured entries in order and returns the first
- * non-null `resolve()` result.
+ * 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<Scopes extends readonly Scope[] = InternallySupportedScopes[]> {
+interface ClientDiscovery {
   /**
    * Stable identifier used in error messages and diagnostics. Convention
    * is to match the plugin id (for example `"cimd"`).
@@ -346,7 +655,7 @@ interface ClientDiscovery<Scopes extends readonly Scope[] = InternallySupportedS
    * - `null`: `getClient()` falls through to the next matching discovery
    *   or to the database record (if any).
    */
-  resolve: (ctx: GenericEndpointContext, clientId: string, existing: SchemaClient<Scopes> | null) => Awaitable<SchemaClient<Scopes> | null>;
+  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
@@ -355,6 +664,337 @@ interface ClientDiscovery<Scopes extends readonly Scope[] = InternallySupportedS
    */
   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
@@ -373,15 +1013,89 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
    */
   scopes?: Scopes;
   /**
-   * List of valid audiences if there are multiple.
+   * 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).
    *
-   * @default baseURL
-   * @example [
-   * 	"https://api.example.com",
-   * 	"https://api.example.com/mcp",
+   * 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.
    */
-  validAudiences?: string[];
+  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.
@@ -416,6 +1130,18 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
    * @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.
    *
@@ -453,8 +1179,9 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
    * Allow unauthenticated dynamic client registration.
    *
    * When enabled, the `/oauth2/register` endpoint accepts requests
-   * without a session, but only for public clients
-   * (`token_endpoint_auth_method: "none"`).
+   * 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
@@ -464,26 +1191,60 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
    */
   allowUnauthenticatedClientRegistration?: boolean;
   /**
-   * Allow dynamic client registration.
+   * 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;
   /**
-   * Discovery implementations consulted by `getClient()` when resolving
-   * a `client_id`. Each entry decides whether it handles the `client_id`
-   * via {@link ClientDiscovery.matches}, then creates, refreshes, or
-   * passes on a client record. Entries run in order; the first one to
-   * return a client wins.
+   * 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.
    *
-   * Each entry also contributes {@link ClientDiscovery.discoveryMetadata}
-   * into the `/.well-known/oauth-authorization-server` and
-   * `/.well-known/openid-configuration` responses.
+   * `headers` is the raw request `Headers`, available to correlate the token
+   * with other request context (a tenant header, a forwarded client identity).
    *
-   * Plugins such as `@better-auth/cimd` install an entry here at init
-   * time; users can also pass discovery implementations directly.
+   * 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
    */
-  clientDiscovery?: ClientDiscovery<Scopes> | ClientDiscovery<Scopes>[];
+  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.
@@ -507,6 +1268,17 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
    * @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.
@@ -592,11 +1364,16 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
    *
    * - `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. Which will
-   * then return the client to the `redirect_uri` with the authorization code.
+   * 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
@@ -790,6 +1567,11 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
      * 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.
@@ -799,6 +1581,11 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
    * 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: {
@@ -822,8 +1609,8 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
   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 resource requesting. Provided by the token endpoint. */
-    resource?: string; /** oAuthClient metadata */
+    scopes: Scopes; /** The resources requested. */
+    resources?: string[]; /** oAuthClient metadata */
     metadata?: Record<string, any>;
   }) => Awaitable<Record<string, any>>;
   /**
@@ -1066,6 +1853,27 @@ interface OAuthOptions<Scopes extends readonly Scope[] = InternallySupportedScop
     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 {
   /**
@@ -1074,6 +1882,13 @@ interface OAuthAuthorizationQuery {
    * 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.
    */
@@ -1096,10 +1911,12 @@ interface OAuthAuthorizationQuery {
    * 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;
+  state?: string;
   /**
    * The client ID. Must be the ID of a registered client.
    */
@@ -1179,6 +1996,118 @@ interface OAuthAuthorizationQuery {
    * 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
@@ -1189,9 +2118,10 @@ interface OAuthAuthorizationQuery {
  */
 interface VerificationValue {
   type: "authorization_code";
-  query: OAuthAuthorizationQuery;
+  query: StoredAuthorizationQuery;
   sessionId: string;
   userId: string;
+  resource?: string[];
   referenceId?: string;
   authTime?: number;
 }
@@ -1260,10 +2190,26 @@ interface SchemaClient<Scopes extends readonly Scope[] = InternallySupportedScop
    * For example, `https://example.com/logout/callback`
    */
   postLogoutRedirectUris?: string[];
-  tokenEndpointAuthMethod?: "none" | "client_secret_basic" | "client_secret_post" | "private_key_jwt";
+  /**
+   * 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 for `private_key_jwt` authentication. Mutually exclusive with `jwksUri`. */
+  /** 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;
@@ -1298,6 +2244,11 @@ interface SchemaClient<Scopes extends readonly Scope[] = InternallySupportedScop
    * 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 */
@@ -1341,6 +2292,11 @@ interface OAuthOpaqueAccessToken<Scopes extends readonly Scope[] = InternallySup
    * 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.
    *
@@ -1351,28 +2307,65 @@ interface OAuthOpaqueAccessToken<Scopes extends readonly Scope[] = InternallySup
   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;
+  sessionId?: string;
   userId: string;
   referenceId?: string;
+  authorizationCodeId?: string;
   clientId?: string;
   expiresAt: Date;
   createdAt: Date;
   /**
-   * When token was revoked. If set, token is considered a replay attack.
+   * 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.
@@ -1384,6 +2377,20 @@ interface OAuthRefreshToken<Scopes extends readonly Scope[] = InternallySupporte
    * 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
@@ -1392,7 +2399,13 @@ 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;
@@ -1402,10 +2415,30 @@ type OAuthConsent<Scopes extends readonly Scope[] = InternallySupportedScopes[]>
 /**
  * Supported grant types of the token endpoint
  */
-type GrantType = "authorization_code" | "client_credentials" | "refresh_token";
-type AuthMethod = "client_secret_basic" | "client_secret_post" | "private_key_jwt";
+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.
  *
@@ -1445,9 +2478,11 @@ interface AuthServerMetadata {
   /**
    * The URL of the dynamic client registration endpoint.
    *
+   * This field is only present when `allowDynamicClientRegistration` is enabled.
+   *
    * @default `/oauth2/register`
    */
-  registration_endpoint: string;
+  registration_endpoint?: string;
   /**
    * Supported scopes.
    */
@@ -1480,7 +2515,7 @@ interface AuthServerMetadata {
    * 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?: AssertionSigningAlgorithm[];
+  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
@@ -1518,7 +2553,7 @@ interface AuthServerMetadata {
    * @default
    * ["client_secret_basic", "client_secret_post"]
    */
-  revocation_endpoint_auth_methods_supported?: AuthMethod[];
+  revocation_endpoint_auth_methods_supported?: TokenEndpointAuthMethod[];
   /**
    * Array containing a list of the JWS signing
    * algorithms ("alg" values) supported by the revocation endpoint for
@@ -1526,7 +2561,7 @@ interface AuthServerMetadata {
    * 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?: AssertionSigningAlgorithm[];
+  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)
@@ -1539,7 +2574,7 @@ interface AuthServerMetadata {
    * @default
    * ["client_secret_basic", "client_secret_post"]
    */
-  introspection_endpoint_auth_methods_supported?: AuthMethod[];
+  introspection_endpoint_auth_methods_supported?: TokenEndpointAuthMethod[];
   /**
    * Array containing a list of the JWS signing
    * algorithms ("alg" values) supported by the introspection endpoint
@@ -1547,7 +2582,7 @@ interface AuthServerMetadata {
    * the "private_key_jwt" and "client_secret_jwt" authentication methods
    * (see field introspection_endpoint_auth_methods_supported).
    */
-  introspection_endpoint_auth_signing_alg_values_supported?: AssertionSigningAlgorithm[];
+  introspection_endpoint_auth_signing_alg_values_supported?: PrivateKeyJwtSigningAlgorithm[];
   /**
    * Supported code challenge methods.
    *
@@ -1573,6 +2608,34 @@ interface AuthServerMetadata {
    * 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:
@@ -1591,19 +2654,16 @@ interface OIDCMetadata extends AuthServerMetadata {
    */
   userinfo_endpoint: string;
   /**
-   * acr_values supported.
-   *
-   * - `urn:mace:incommon:iap:silver`: Silver level of assurance
-   * - `urn:mace:incommon:iap:bronze`: Bronze level of assurance
+   * Authentication Context Class Reference values supported.
    *
-   * Determination of acr_value is considered bronze by default.
-   * Silver level determination coming soon.
+   * Better Auth does not advertise this field by default because it does not
+   * currently evaluate requested Authentication Context Class References.
    *
    * @default
-   * ["urn:mace:incommon:iap:bronze"]
-   * @see https://incommon.org/federation/attributes.html
+   * undefined
+   * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
    */
-  acr_values_supported: string[];
+  acr_values_supported?: string[];
   /**
    * Supported subject types.
    *
@@ -1631,12 +2691,36 @@ interface OIDCMetadata extends AuthServerMetadata {
    * ["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
    *
@@ -1675,7 +2759,23 @@ interface OAuthClient {
   software_statement?: string;
   redirect_uris: string[];
   post_logout_redirect_uris?: string[];
-  token_endpoint_auth_method?: "none" | "client_secret_basic" | "client_secret_post" | "private_key_jwt";
+  /**
+   * 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;
@@ -1688,10 +2788,17 @@ interface OAuthClient {
    *
    * @default true
    *
-   * Note: PKCE is always required for public clients and when
-   * requesting offline_access scope, regardless of this setting.
+   * 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.
    *
@@ -1739,4 +2846,4 @@ interface ResourceServerMetadata {
   dpop_bound_access_tokens_required?: boolean;
 }
 //#endregion
-export { Scope as _, OIDCMetadata as a, Awaitable as b, AuthorizePrompt as c, OAuthConsent as d, OAuthOpaqueAccessToken as f, SchemaClient as g, Prompt as h, OAuthClient as i, ClientDiscovery as l, OAuthRefreshToken as m, AuthServerMetadata as n, ResourceServerMetadata as o, OAuthOptions as p, GrantType as r, TokenEndpointAuthMethod as s, AuthMethod as t, OAuthAuthorizationQuery as u, StoreTokenType as v, VerificationValue as y };
+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 };