Configuration and Discovery

/**
 * Performs Authorization Server Metadata discovery
 * @param server - URL of the Authorization Server's Issuer Identifier  
 * @param clientId - Client Identifier at the Authorization Server
 * @param metadata - Client metadata or client secret string
 * @param clientAuthentication - Client authentication method (defaults to ClientSecretPost)
 * @param options - Discovery options
 * @returns Promise resolving to Configuration instance
 */
function discovery(
  server: URL,
  clientId: string,
  metadata?: Partial<ClientMetadata> | string,
  clientAuthentication?: ClientAuth,
  options?: DiscoveryRequestOptions
): Promise<Configuration>;

import * as client from "openid-client";

// Basic discovery with client secret
const config = await client.discovery(
  new URL("https://accounts.google.com"),
  "your-client-id",
  "your-client-secret"
);

// Discovery with client metadata object
const config = await client.discovery(
  new URL("https://example.com"),
  "client-id",
  {
    client_secret: "secret",
    use_mtls_endpoint_aliases: true
  }
);

// Discovery with specific authentication method
const config = await client.discovery(
  new URL("https://example.com"),
  "client-id",
  undefined, // no client secret for public client
  client.None()
);

// Discovery with options
const config = await client.discovery(
  new URL("https://example.com"),
  "client-id",
  "client-secret",
  undefined, // default auth method
  {
    algorithm: "oauth2", // use OAuth 2.0 discovery instead of OIDC
    timeout: 60, // 60 second timeout
    execute: [client.allowInsecureRequests] // allow HTTP for development
  }
);

/**
 * Configuration class combining server and client metadata
 */
class Configuration implements ConfigurationMethods, ConfigurationProperties {
  constructor(
    server: ServerMetadata,
    clientId: string,
    metadata?: Partial<ClientMetadata> | string,
    clientAuthentication?: ClientAuth
  );
  
  serverMetadata(): Readonly<ServerMetadata> & ServerMetadataHelpers;
  clientMetadata(): Readonly<OmitSymbolProperties<ClientMetadata>>;
  
  timeout?: number;
  [customFetch]?: CustomFetch;
}

import * as client from "openid-client";

// Manual configuration with known server metadata
const serverMetadata: client.ServerMetadata = {
  issuer: "https://example.com",
  authorization_endpoint: "https://example.com/auth",
  token_endpoint: "https://example.com/token",
  userinfo_endpoint: "https://example.com/userinfo",
  jwks_uri: "https://example.com/.well-known/jwks.json",
  // ... other required metadata
};

const config = new client.Configuration(
  serverMetadata,
  "client-id",
  "client-secret"
);

// Access metadata
const server = config.serverMetadata();
const clientInfo = config.clientMetadata();

// Check server capabilities  
if (server.supportsPKCE()) {
  console.log("Server supports PKCE");
}

/**
 * Performs dynamic client registration with discovery
 * @param server - Authorization Server issuer URL
 * @param metadata - Client metadata to register
 * @param clientAuthentication - Authentication method for registration
 * @param options - Registration options
 * @returns Promise resolving to Configuration with registered client
 */
function dynamicClientRegistration(
  server: URL,
  metadata: Partial<ClientMetadata>,
  clientAuthentication?: ClientAuth,
  options?: DynamicClientRegistrationRequestOptions
): Promise<Configuration>;

import * as client from "openid-client";

// Register a new client
const config = await client.dynamicClientRegistration(
  new URL("https://example.com"),
  {
    redirect_uris: ["https://myapp.com/callback"],
    response_types: ["code"],
    grant_types: ["authorization_code", "refresh_token"],
    application_type: "web",
    client_name: "My Application"
  }
);

// Registration with initial access token
const config = await client.dynamicClientRegistration(
  new URL("https://example.com"),
  {
    redirect_uris: ["https://myapp.com/callback"],
    response_types: ["code"]
  },
  undefined, // default auth
  {
    initialAccessToken: "bearer-token-for-registration"
  }
);

interface DiscoveryRequestOptions {
  /** Custom fetch implementation */
  [customFetch]?: CustomFetch;
  /** Discovery algorithm: 'oidc' or 'oauth2' */
  algorithm?: 'oidc' | 'oauth2';
  /** Configuration methods to execute after instantiation */
  execute?: Array<(config: Configuration) => void>;
  /** Timeout in seconds (default: 30) */
  timeout?: number;
}

interface DynamicClientRegistrationRequestOptions extends DiscoveryRequestOptions, DPoPOptions {
  /** Access token for client registration endpoint */
  initialAccessToken?: string;
}

interface ServerMetadataHelpers {
  /**
   * Check if server supports PKCE with specified method
   * @param method - PKCE method (default: 'S256')
   * @returns True if PKCE is supported
   */
  supportsPKCE(method?: string): boolean;
}

interface ConfigurationProperties {
  /** Custom fetch implementation for HTTP requests */
  [customFetch]?: CustomFetch;
  /** Timeout in seconds for HTTP requests (default: 30) */
  timeout?: number;
}

interface ConfigurationMethods {
  /** Get server metadata with helpers */
  serverMetadata(): Readonly<ServerMetadata> & ServerMetadataHelpers;
  /** Get client metadata */
  clientMetadata(): Readonly<OmitSymbolProperties<ClientMetadata>>;
}

interface ServerMetadata extends AuthorizationServer {
  // Standard OAuth 2.0/OIDC Authorization Server metadata
  issuer: string;
  authorization_endpoint: string;
  token_endpoint: string;
  userinfo_endpoint?: string;
  jwks_uri?: string;
  registration_endpoint?: string;
  scopes_supported?: string[];
  response_types_supported?: string[];
  grant_types_supported?: string[];
  token_endpoint_auth_methods_supported?: string[];
  // ... and many other standard metadata fields
}

interface ClientMetadata extends Client {
  /** Client secret for confidential clients */
  client_secret?: string;
  /** Use mutual TLS endpoint aliases */
  use_mtls_endpoint_aliases?: boolean;
  /** Client ID */
  client_id?: string;
  /** Redirect URIs */
  redirect_uris?: string[];
  /** Response types */
  response_types?: string[];
  /** Grant types */
  grant_types?: string[];
  /** Application type ('web' or 'native') */
  application_type?: string;
  /** Client name */
  client_name?: string;
  // ... and other standard client metadata fields
}