@better-auth/cimd 1.7.0-rc.2 → 1.7.0-rc.3

package/README.md

@@ -1,6 +1,6 @@
 # Better Auth CIMD Plugin
 
-Client ID Metadata Document plugin for [Better Auth](https://www.better-auth.com): unauthenticated dynamic client discovery over HTTPS, the mechanism [MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization#client-id-metadata-documents-flow) uses for authorization servers to discover clients without prior registration.
+Client ID Metadata Document draft-02 plugin for [Better Auth](https://www.better-auth.com): unauthenticated client discovery over HTTPS. An explicit metadata profile applies the draft-00 requirements pinned by [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents).
 
 ## Installation
 

package/dist/index.d.mts

@@ -1,22 +1,114 @@
-import { ClientDiscovery, SchemaClient, Scope } from "@better-auth/oauth-provider";
+import { ClientDiscovery, ClientMetadataResourceFetch, OAuthClientMetadata, SchemaClient, Scope } from "@better-auth/oauth-provider";
 import { GenericEndpointContext } from "@better-auth/core";
 //#region src/types.d.ts
+type CimdMetadataProfile = "mcp-2026-07-28";
+interface CimdClientCreatedEvent {
+  /** Newly persisted discovery-owned OAuth client. */
+  client: SchemaClient<Scope[]>;
+  /** Validated Client ID Metadata Document that produced the client. */
+  clientMetadataDocument: OAuthClientMetadata;
+  /** Better Auth endpoint context for the discovery request. */
+  context: GenericEndpointContext;
+}
+interface CimdClientRefreshedEvent {
+  /** Discovery-owned OAuth client after metadata reconciliation. */
+  client: SchemaClient<Scope[]>;
+  /** Client state captured before metadata reconciliation. */
+  previousClient: SchemaClient<Scope[]>;
+  /** Validated Client ID Metadata Document used for reconciliation. */
+  clientMetadataDocument: OAuthClientMetadata;
+  /** Better Auth endpoint context for the discovery request. */
+  context: GenericEndpointContext;
+}
+interface CimdMetadataFetchPolicy {
+  /**
+   * Minimum time between metadata fetch starts for one exact client ID.
+   * Fresh-cache hits and callers joining an in-flight fetch do not consume
+   * this interval. Numeric values are seconds. Set to `0` to disable
+   * per-client pacing.
+   *
+   * @default 1
+   */
+  minimumFetchInterval?: number | string;
+  /**
+   * Maximum metadata fetches in flight across the plugin instance.
+   *
+   * @default 16
+   */
+  maximumConcurrentFetches?: number;
+  /**
+   * Maximum metadata fetches in flight for one URL origin.
+   *
+   * @default 4
+   */
+  maximumConcurrentFetchesPerOrigin?: number;
+  /**
+   * Maximum fetch starts in a rolling 60-second window across the
+   * plugin instance.
+   *
+   * @default 120
+   */
+  maximumFetchesPerMinute?: number;
+  /**
+   * Maximum fetch starts in a rolling 60-second window for one URL
+   * origin.
+   *
+   * @default 30
+   */
+  maximumFetchesPerOriginPerMinute?: number;
+}
 /**
  * Options for the Client ID Metadata Document plugin.
  *
- * @see https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-02
  */
 interface CimdOptions {
   /**
-   * How frequently to re-fetch a client's metadata document to pick up
-   * changes from the client.
+   * Fetch transport for metadata documents and discovery-owned metadata
+   * resources such as `jwks_uri`.
+   *
+   * The transport MUST resolve the hostname exactly once, reject RFC 6890
+   * special-use addresses, pin the approved address for the connection, and
+   * refuse redirects. Those guarantees cannot be implemented by wrapping the
+   * standard Fetch API after DNS resolution, so the application must provide
+   * them at its runtime-specific network boundary.
+   */
+  fetchClientMetadataResource: ClientMetadataResourceFetch;
+  /**
+   * Apply an additional protocol profile to otherwise generic draft-02
+   * metadata validation.
+   *
+   * The MCP 2026-07-28 profile requires `client_name` and `redirect_uris`
+   * because that MCP revision normatively pins CIMD draft-00.
+   */
+  metadataProfile?: CimdMetadataProfile;
+  /**
+   * Maximum and fallback cache freshness lifetime for a client's metadata
+   * document. An expired entry is revalidated on the next client resolution;
+   * the plugin does not perform periodic or background fetches.
    *
    * Accepts a number of seconds or a duration string (e.g. `"60m"`,
    * `"1d"`).
    *
    * @default "60m"
    */
-  refreshRate?: number | string;
+  metadataRevalidationInterval?: number | string;
+  /**
+   * Bounded request-amplification policy for metadata document fetches.
+   *
+   * A permitted fetch consumes its concurrency and rolling-window budget when
+   * it starts. Same-client concurrent resolutions coalesce, while fresh-cache
+   * hits consume no budget. Limits reject immediately rather than queueing.
+   */
+  metadataFetchPolicy?: CimdMetadataFetchPolicy;
+  /**
+   * Maximum number of validated metadata documents retained by this plugin
+   * instance. The least-recently-used entry is evicted when the bound is
+   * reached.
+   *
+   * @default 1000
+   */
+  maxCacheEntries?: number;
   /**
    * Metadata fields whose URL values must share the same origin as the
    * `client_id` URL. Prevents a client from claiming URIs on a different
@@ -25,107 +117,87 @@ interface CimdOptions {
    * Pass an empty array to disable origin binding (not recommended for
    * production).
    *
-   * @default ["redirect_uris", "post_logout_redirect_uris", "client_uri"]
-   */
-  originBoundFields?: string[];
-  /**
-   * Permit loopback `client_id` URLs (`localhost`, `127.0.0.0/8`, `::1`,
-   * `*.localhost`), including plain HTTP, so an auth server can fetch a
-   * metadata document hosted on the same machine. Off by default; enable
-   * only for local development.
+   * Redirect URIs are deliberately excluded by default: exact redirect URI
+   * matching remains mandatory at authorization time, while native and
+   * distributed clients commonly use a redirect origin different from their
+   * metadata-document origin.
    *
-   * @default false
+   * @default ["post_logout_redirect_uris", "client_uri"]
    */
-  allowLoopback?: boolean;
+  originBoundFields?: readonly string[];
   /**
    * Pre-fetch gate called before a metadata document is requested. Return
    * `false` to reject the `client_id` URL.
    *
    * Use this for origin allowlists, per-host rate limiting, or integrating
-   * with an external trust service. Hostname-based DNS defenses (beyond
-   * the built-in IP-literal check) belong here, since the plugin is
-   * runtime-agnostic and does not perform DNS resolution.
+   * with an external trust service. It is application policy, not a
+   * substitute for the required transport's resolve-once and connection-
+   * pinning guarantees; resolving here would introduce a TOCTOU boundary.
    *
    * @default always allow
    */
-  allowFetch?: (url: string, ctx: GenericEndpointContext) => boolean | Promise<boolean>;
+  isMetadataDocumentUrlAllowed?: (clientIdUrl: string, context: GenericEndpointContext) => boolean | Promise<boolean>;
   /**
    * Called after a client is created from a metadata document for the
-   * first time. Use this to assign trust levels, prefetch logos, or
-   * perform other post-creation processing.
+   * first time. Use this to assign local trust, emit an audit event, or
+   * perform other post-creation processing. Better Auth does not fetch or
+   * render metadata-owned remote assets such as `logo_uri`.
+   *
+   * This is a best-effort notification. A rejected callback is logged and
+   * does not roll back an otherwise valid registration.
    */
-  onClientCreated?: (data: {
-    client: SchemaClient<Scope[]>;
-    metadata: Record<string, unknown>;
-    ctx: GenericEndpointContext;
-  }) => void | Promise<void>;
+  onClientCreated?: (event: CimdClientCreatedEvent) => void | Promise<void>;
   /**
    * Called after a client is refreshed from a re-fetched metadata
    * document. Use this for change-detection logging or updating derived
    * fields.
+   *
+   * This is a best-effort notification. A rejected callback is logged and
+   * does not roll back an otherwise valid refresh.
    */
-  onClientRefreshed?: (data: {
-    client: SchemaClient<Scope[]>;
-    metadata: Record<string, unknown>;
-    ctx: GenericEndpointContext;
-  }) => void | Promise<void>;
+  onClientRefreshed?: (event: CimdClientRefreshedEvent) => void | Promise<void>;
 }
 //#endregion
-//#region src/resolver.d.ts
-/**
- * Signature of the `resolve` function on a {@link ClientDiscovery}. Kept
- * here to avoid a circular import back into `@better-auth/oauth-provider`.
- */
-type CimdResolver = (ctx: GenericEndpointContext, clientId: string, existing: SchemaClient<Scope[]> | null) => Promise<SchemaClient<Scope[]> | null>;
-/**
- * Build the `resolve` function for a CIMD {@link ClientDiscovery}.
- *
- * Exposed for advanced composition. Most users should call
- * {@link cimdClientDiscovery} (to contribute a complete discovery through
- * `oauthProvider({ extensions: [{ clientDiscovery }] })`) or install the
- * `cimd()` plugin.
- */
-declare function createCimdResolver(cimdOptions?: CimdOptions): CimdResolver;
-//#endregion
 //#region src/validate-metadata-document.d.ts
-interface ClientIdMetadataDocumentResult {
-  valid: boolean;
-  error?: string;
+type CimdMetadataValidationResult = {
+  valid: true;
+  metadata: OAuthClientMetadata;
+  error?: never;
   warnings?: string[];
-}
-interface ClientIdUrlOptions {
-  /**
-   * Permit loopback `client_id` URLs (`localhost`, `127.0.0.0/8`, `::1`,
-   * `*.localhost`) and plain HTTP for them. Off by default.
-   */
-  allowLoopback?: boolean;
+} | {
+  valid: false;
+  error: string;
+  metadata?: never;
+  warnings?: string[];
+};
+interface CimdMetadataValidationOptions {
+  originBoundFields?: readonly string[];
+  metadataProfile?: CimdMetadataProfile;
 }
 /**
  * Detect a URL-formatted client_id (Client ID Metadata Document pattern).
  *
- * HTTPS URLs always match; plain HTTP matches only loopback hosts, and only
- * when `allowLoopback` is set. This is a routing predicate, not a security
- * gate: it performs no DNS resolution, so callers MUST also run
+ * HTTPS URLs match. This is a routing predicate, not a security gate: it
+ * performs no DNS resolution, so callers MUST also run
  * {@link validateClientIdUrl} (and a fetch-time policy) before fetching.
  */
-declare function isUrlClientId(clientId: string, options?: ClientIdUrlOptions): boolean;
+declare function isCimdClientIdUrlCandidate(clientId: string): boolean;
 /**
- * Validate a client_id URL per IETF draft §3.
+ * Validate a client_id URL per Client ID Metadata Document draft-02 §3.
  * Returns null on success, an error string on failure.
  *
- * Loopback hosts are rejected unless `allowLoopback` is set; every other
- * non-public host (private, link-local, cloud-metadata, IPv6 tunnels) is
- * rejected.
+ * Loopback and every other non-public host (private, link-local,
+ * cloud-metadata, IPv6 tunnels) are rejected.
  */
-declare function validateClientIdUrl(url: string, options?: ClientIdUrlOptions): string | null;
+declare function validateClientIdUrl(url: string): string | null;
 /**
  * Validate a fetched Client ID Metadata Document per §4.1.
  *
- * @param fetchUrl - The URL the document was fetched from.
+ * @param clientIdUrl - The URL the document was fetched from.
  * @param raw - The parsed JSON body of the response.
- * @param originBoundFields - Fields whose URL values must share the same origin as the `client_id` URL.
+ * @param options - Generic draft-02 validation options and an optional protocol profile.
  */
-declare function validateCimdMetadata(fetchUrl: string, raw: unknown, originBoundFields?: string[]): ClientIdMetadataDocumentResult;
+declare function validateCimdMetadata(clientIdUrl: string, raw: unknown, options?: CimdMetadataValidationOptions): CimdMetadataValidationResult;
 //#endregion
 //#region src/index.d.ts
 declare module "@better-auth/core" {
@@ -143,22 +215,23 @@ declare module "@better-auth/core" {
  * install the {@link cimd} plugin instead, which contributes this discovery
  * alongside whatever else is configured.
  */
-declare function cimdClientDiscovery(options?: CimdOptions): ClientDiscovery;
+declare function createCimdClientDiscovery(options: CimdOptions): ClientDiscovery;
 /**
  * Client ID Metadata Document plugin.
  *
  * Adds unauthenticated dynamic client discovery over HTTPS to an
  * `oauth-provider` instance. Clients identify themselves by providing
  * an HTTPS URL as their `client_id`; the plugin fetches and validates
- * the document at that URL, then creates a public client record.
+ * the document at that URL, then creates a client record whose authentication
+ * behavior is determined by `token_endpoint_auth_method`.
  *
- * See {@link https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/ | the IETF draft}
- * and {@link https://modelcontextprotocol.io/specification/draft/basic/authorization#client-id-metadata-documents-flow | the MCP authorization spec}.
+ * See {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-02 | Client ID Metadata Document draft-02}
+ * and {@link https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents | the MCP authorization spec}.
  */
-declare const cimd: (options?: CimdOptions) => {
+declare const cimd: (options: CimdOptions) => {
   id: "cimd";
   version: string;
   init(ctx: import("better-auth").AuthContext): void;
 };
 //#endregion
-export { type CimdOptions, type ClientIdMetadataDocumentResult, type ClientIdUrlOptions, cimd, cimdClientDiscovery, createCimdResolver, isUrlClientId, validateCimdMetadata, validateClientIdUrl };
+export { type CimdClientCreatedEvent, type CimdClientRefreshedEvent, type CimdMetadataFetchPolicy, type CimdMetadataProfile, type CimdMetadataValidationOptions, type CimdMetadataValidationResult, type CimdOptions, cimd, createCimdClientDiscovery, isCimdClientIdUrlCandidate, validateCimdMetadata, validateClientIdUrl };