@better-auth/oauth-provider 1.7.0-beta.5 → 1.7.0-beta.6

package/dist/{oauth-BXrYl5x6.d.mts → oauth-CaXmZpoL.d.mts}

@@ -1,6 +1,7 @@
+import * as z from "zod";
 import { PrivateKeyJwtSigningAlgorithm } from "@better-auth/core/oauth2";
-import { JWSAlgorithms } from "better-auth/plugins";
 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";
 
@@ -140,6 +141,11 @@ declare const schema: {
         type: "boolean";
         required: false;
       };
+      dpopBoundAccessTokens: {
+        type: "boolean";
+        required: false;
+        defaultValue: false;
+      };
       referenceId: {
         type: "string";
         required: false;
@@ -150,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"
    *
@@ -212,6 +353,10 @@ declare const schema: {
         type: "date";
         required: false;
       };
+      confirmation: {
+        type: "json";
+        required: false;
+      };
       scopes: {
         type: "string[]";
         required: true;
@@ -219,7 +364,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
@@ -292,6 +437,10 @@ declare const schema: {
         type: "date";
         required: false;
       };
+      confirmation: {
+        type: "json";
+        required: false;
+      };
       scopes: {
         type: "string[]";
         required: true;
@@ -365,8 +514,78 @@ declare const schema: {
 //#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";
@@ -376,11 +595,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"`).
@@ -402,7 +621,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
@@ -411,6 +630,318 @@ 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[];
+  /**
+   * 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;
+  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[]>;
+}
+/**
+ * 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
@@ -429,15 +960,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",
    * ]
+   * ```
    */
-  validAudiences?: string[];
+  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.
@@ -520,26 +1125,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 public-only: unauthenticated registration constrained to public
+   *   clients, 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.
    *
-   * Each entry also contributes {@link ClientDiscovery.discoveryMetadata}
-   * into the `/.well-known/oauth-authorization-server` and
-   * `/.well-known/openid-configuration` responses.
+   * `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.
    *
-   * Plugins such as `@better-auth/cimd` install an entry here at init
-   * time; users can also pass discovery implementations directly.
+   * 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.
    */
-  clientDiscovery?: ClientDiscovery<Scopes> | ClientDiscovery<Scopes>[];
+  extensions?: OAuthProviderExtension[];
   /**
    * List of scopes for newly registered clients
    * if not requested.
@@ -1122,6 +1761,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 {
   /**
@@ -1237,11 +1897,100 @@ interface OAuthAuthorizationQuery {
    * with the Claim Value being the nonce value sent in the Authentication Request.
    */
   nonce?: string;
+  /**
+   * 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;
+}
 /**
  * Stored within the verification.value field
  * in JSON format.
@@ -1339,7 +2088,7 @@ interface SchemaClient<Scopes extends readonly Scope[] = InternallySupportedScop
    * @default false
    */
   backchannelLogoutSessionRequired?: boolean;
-  tokenEndpointAuthMethod?: "none" | "client_secret_basic" | "client_secret_post" | "private_key_jwt";
+  tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
   grantTypes?: GrantType[];
   responseTypes?: "code"[];
   /** Client's JSON Web Key Set for `private_key_jwt` authentication. Mutually exclusive with `jwksUri`. */
@@ -1377,6 +2126,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 */
@@ -1446,6 +2200,11 @@ interface OAuthOpaqueAccessToken<Scopes extends readonly Scope[] = InternallySup
    * Resources allowed for this access token.
    */
   resources?: 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
@@ -1477,6 +2236,11 @@ interface OAuthRefreshToken<Scopes extends readonly Scope[] = InternallySupporte
    * Resources allowed for this refresh token
    */
   resources?: 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
@@ -1496,10 +2260,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.
  *
@@ -1614,7 +2398,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
@@ -1635,7 +2419,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
@@ -1691,6 +2475,12 @@ interface AuthServerMetadata {
    * @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:
@@ -1809,7 +2599,7 @@ interface OAuthClient {
    * @see https://openid.net/specs/openid-connect-backchannel-1_0.html#RPMetadata
    */
   backchannel_logout_session_required?: boolean;
-  token_endpoint_auth_method?: "none" | "client_secret_basic" | "client_secret_post" | "private_key_jwt";
+  token_endpoint_auth_method?: TokenEndpointAuthMethod;
   grant_types?: GrantType[];
   response_types?: "code"[];
   public?: boolean;
@@ -1826,6 +2616,12 @@ interface OAuthClient {
    * requesting offline_access scope, regardless of this setting.
    */
   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.
    *
@@ -1873,4 +2669,4 @@ interface ResourceServerMetadata {
   dpop_bound_access_tokens_required?: boolean;
 }
 //#endregion
-export { SchemaClient as _, OAuthClient as a, VerificationValue as b, TokenEndpointAuthMethod as c, OAuthAuthorizationQuery as d, OAuthConsent as f, Prompt as g, OAuthRefreshToken as h, GrantType as i, AuthorizePrompt as l, OAuthOptions as m, AuthServerMetadata as n, OIDCMetadata as o, OAuthOpaqueAccessToken as p, BearerMethodsSupported as r, ResourceServerMetadata as s, AuthMethod as t, ClientDiscovery as u, Scope as v, Awaitable as x, StoreTokenType as y };
+export { OAuthProviderExtension as A, StoreTokenType as B, OAuthConsent as C, OAuthOpaqueAccessToken as D, OAuthMetadataExtensionInput as E, OAuthTokenResponse as F, ClientRegistrationRequest 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, ResourceUriSchema as U, VerificationValue as V, 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 };