diff --git a/docs/references/js/README.md b/docs/references/js/README.md index 2a6f065..06a9529 100644 --- a/docs/references/js/README.md +++ b/docs/references/js/README.md @@ -4,7 +4,7 @@ sidebar_label: Node.js SDK # MCP Auth Node.js SDK reference -## Classes {#classes} +## Classes - [MCPAuth](/references/js/classes/MCPAuth.md) - [MCPAuthAuthServerError](/references/js/classes/MCPAuthAuthServerError.md) @@ -13,7 +13,7 @@ sidebar_label: Node.js SDK - [MCPAuthError](/references/js/classes/MCPAuthError.md) - [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) -## Type Aliases {#type-aliases} +## Type Aliases - [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) - [AuthServerConfig](/references/js/type-aliases/AuthServerConfig.md) @@ -21,6 +21,7 @@ sidebar_label: Node.js SDK - [AuthServerConfigErrorCode](/references/js/type-aliases/AuthServerConfigErrorCode.md) - [AuthServerConfigWarning](/references/js/type-aliases/AuthServerConfigWarning.md) - [AuthServerConfigWarningCode](/references/js/type-aliases/AuthServerConfigWarningCode.md) +- [AuthServerDiscoveryConfig](/references/js/type-aliases/AuthServerDiscoveryConfig.md) - [AuthServerErrorCode](/references/js/type-aliases/AuthServerErrorCode.md) - [~~AuthServerModeConfig~~](/references/js/type-aliases/AuthServerModeConfig.md) - [AuthServerSuccessCode](/references/js/type-aliases/AuthServerSuccessCode.md) @@ -33,12 +34,13 @@ sidebar_label: Node.js SDK - [MCPAuthConfig](/references/js/type-aliases/MCPAuthConfig.md) - [MCPAuthTokenVerificationErrorCode](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) - [ProtectedResourceMetadata](/references/js/type-aliases/ProtectedResourceMetadata.md) +- [ResolvedAuthServerConfig](/references/js/type-aliases/ResolvedAuthServerConfig.md) - [ResourceServerModeConfig](/references/js/type-aliases/ResourceServerModeConfig.md) - [ValidateIssuerFunction](/references/js/type-aliases/ValidateIssuerFunction.md) - [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) - [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) -## Variables {#variables} +## Variables - [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) - [authServerErrorDescription](/references/js/variables/authServerErrorDescription.md) @@ -51,9 +53,10 @@ sidebar_label: Node.js SDK - [tokenVerificationErrorDescription](/references/js/variables/tokenVerificationErrorDescription.md) - [validateServerConfig](/references/js/variables/validateServerConfig.md) -## Functions {#functions} +## Functions - [createVerifyJwt](/references/js/functions/createVerifyJwt.md) - [fetchServerConfig](/references/js/functions/fetchServerConfig.md) - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) +- [getIssuer](/references/js/functions/getIssuer.md) - [handleBearerAuth](/references/js/functions/handleBearerAuth.md) diff --git a/docs/references/js/classes/MCPAuth.md b/docs/references/js/classes/MCPAuth.md index 84be260..7c5e0d1 100644 --- a/docs/references/js/classes/MCPAuth.md +++ b/docs/references/js/classes/MCPAuth.md @@ -10,23 +10,51 @@ authentication policies for your protected resources. It is initialized with your server configurations and provides a `bearerAuth` method to generate Express middleware for token-based authentication. -## Example {#example} +## Example -### Usage in `resource server` mode {#usage-in-resource-server-mode} +### Usage in `resource server` mode This is the recommended approach for new applications. +#### Option 1: Discovery config (recommended for edge runtimes) + +Use this when you want metadata to be fetched on-demand. This is especially useful for +edge runtimes like Cloudflare Workers where top-level async fetch is not allowed. + ```ts import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; +import { MCPAuth } from 'mcp-auth'; const app = express(); +const resourceIdentifier = 'https://api.example.com/notes'; +const mcpAuth = new MCPAuth({ + protectedResources: [ + { + metadata: { + resource: resourceIdentifier, + // Just pass issuer and type - metadata will be fetched on first request + authorizationServers: [{ issuer: 'https://auth.logto.io/oidc', type: 'oidc' }], + scopesSupported: ['read:notes', 'write:notes'], + }, + }, + ], +}); +``` + +#### Option 2: Resolved config (pre-fetched metadata) + +Use this when you want to fetch and validate metadata at startup time. + +```ts +import express from 'express'; +import { MCPAuth, fetchServerConfig } from 'mcp-auth'; + +const app = express(); const resourceIdentifier = 'https://api.example.com/notes'; const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); const mcpAuth = new MCPAuth({ - // `protectedResources` can be a single configuration object or an array of them. protectedResources: [ { metadata: { @@ -37,7 +65,11 @@ const mcpAuth = new MCPAuth({ }, ], }); +``` + +#### Using the middleware +```ts // Mount the router to handle Protected Resource Metadata app.use(mcpAuth.protectedResourceMetadataRouter()); @@ -56,20 +88,18 @@ app.get( ); ``` -### Legacy Usage in `authorization server` mode (Deprecated) {#legacy-usage-in-authorization-server-mode-deprecated} +### Legacy Usage in `authorization server` mode (Deprecated) This approach is supported for backward compatibility. ```ts import express from 'express'; -import { MCPAuth, fetchServerConfig } from 'mcp-auth'; +import { MCPAuth } from 'mcp-auth'; const app = express(); const mcpAuth = new MCPAuth({ - server: await fetchServerConfig( - 'https://auth.logto.io/oidc', - { type: 'oidc' } - ), + // Discovery config - metadata fetched on-demand + server: { issuer: 'https://auth.logto.io/oidc', type: 'oidc' }, }); // Mount the router to handle legacy Authorization Server Metadata @@ -86,9 +116,9 @@ app.get( ); ``` -## Constructors {#constructors} +## Constructors -### Constructor {#constructor} +### Constructor ```ts new MCPAuth(config: MCPAuthConfig): MCPAuth; @@ -97,21 +127,21 @@ new MCPAuth(config: MCPAuthConfig): MCPAuth; Creates an instance of MCPAuth. It validates the entire configuration upfront to fail fast on errors. -#### Parameters {#parameters} +#### Parameters -##### config {#config} +##### config [`MCPAuthConfig`](/references/js/type-aliases/MCPAuthConfig.md) The authentication configuration. -#### Returns {#returns} +#### Returns `MCPAuth` -## Properties {#properties} +## Properties -### config {#config} +### config ```ts readonly config: MCPAuthConfig; @@ -119,11 +149,11 @@ readonly config: MCPAuthConfig; The authentication configuration. -## Methods {#methods} +## Methods -### bearerAuth() {#bearerauth} +### bearerAuth() -#### Call Signature {#call-signature} +#### Call Signature ```ts bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit): RequestHandler; @@ -132,9 +162,9 @@ bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit @@ -158,19 +188,19 @@ Optional configuration for the Bearer auth handler. [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) for the available configuration options (excluding `verifyAccessToken` and `issuer`). -##### Returns {#returns} +##### Returns `RequestHandler` An Express middleware function that verifies the access token and adds the verification result to the request object (`req.auth`). -##### See {#see} +##### See [handleBearerAuth](/references/js/functions/handleBearerAuth.md) for the implementation details and the extended types of the `req.auth` (`AuthInfo`) object. -#### Call Signature {#call-signature} +#### Call Signature ```ts bearerAuth(mode: "jwt", config?: Omit & VerifyJwtConfig): RequestHandler; @@ -182,9 +212,9 @@ Creates a Bearer auth handler (Express middleware) that verifies the access toke In the `'jwt'` mode, the handler will create a JWT verification function using the JWK Set from the authorization server's JWKS URI. -##### Parameters {#parameters} +##### Parameters -###### mode {#mode} +###### mode `"jwt"` @@ -194,7 +224,7 @@ The mode of verification for the access token. Currently, only 'jwt' is supporte [VerifyAccessTokenMode](/references/js/type-aliases/VerifyAccessTokenMode.md) for the available modes. -###### config? {#config} +###### config? `Omit`\<[`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md), `"issuer"` \| `"verifyAccessToken"`\> & `VerifyJwtConfig` @@ -208,26 +238,26 @@ verification. - [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) for the available configuration options (excluding `verifyAccessToken` and `issuer`). -##### Returns {#returns} +##### Returns `RequestHandler` An Express middleware function that verifies the access token and adds the verification result to the request object (`req.auth`). -##### See {#see} +##### See [handleBearerAuth](/references/js/functions/handleBearerAuth.md) for the implementation details and the extended types of the `req.auth` (`AuthInfo`) object. -##### Throws {#throws} +##### Throws if the JWKS URI is not provided in the server metadata when using the `'jwt'` mode. *** -### ~~delegatedRouter()~~ {#delegatedrouter} +### ~~delegatedRouter()~~ ```ts delegatedRouter(): Router; @@ -236,18 +266,18 @@ delegatedRouter(): Router; Creates a delegated router for serving legacy OAuth 2.0 Authorization Server Metadata endpoint (`/.well-known/oauth-authorization-server`) with the metadata provided to the instance. -#### Returns {#returns} +#### Returns `Router` A router that serves the OAuth 2.0 Authorization Server Metadata endpoint with the metadata provided to the instance. -#### Deprecated {#deprecated} +#### Deprecated Use [protectedResourceMetadataRouter](/references/js/classes/MCPAuth.md#protectedresourcemetadatarouter) instead. -#### Example {#example} +#### Example ```ts import express from 'express'; @@ -258,13 +288,13 @@ const mcpAuth: MCPAuth; // Assume this is initialized app.use(mcpAuth.delegatedRouter()); ``` -#### Throws {#throws} +#### Throws If called in `resource server` mode. *** -### protectedResourceMetadataRouter() {#protectedresourcemetadatarouter} +### protectedResourceMetadataRouter() ```ts protectedResourceMetadataRouter(): Router; @@ -276,17 +306,17 @@ for all configured resources. This router automatically creates the correct `.well-known` endpoints for each resource identifier provided in your configuration. -#### Returns {#returns} +#### Returns `Router` A router that serves the OAuth 2.0 Protected Resource Metadata endpoint. -#### Throws {#throws} +#### Throws If called in `authorization server` mode. -#### Example {#example} +#### Example ```ts import express from 'express'; diff --git a/docs/references/js/classes/MCPAuthAuthServerError.md b/docs/references/js/classes/MCPAuthAuthServerError.md index f76f24c..cc3f26b 100644 --- a/docs/references/js/classes/MCPAuthAuthServerError.md +++ b/docs/references/js/classes/MCPAuthAuthServerError.md @@ -6,51 +6,51 @@ sidebar_label: MCPAuthAuthServerError Error thrown when there is an issue with the remote authorization server. -## Extends {#extends} +## Extends - [`MCPAuthError`](/references/js/classes/MCPAuthError.md) -## Constructors {#constructors} +## Constructors -### Constructor {#constructor} +### Constructor ```ts new MCPAuthAuthServerError(code: AuthServerErrorCode, cause?: unknown): MCPAuthAuthServerError; ``` -#### Parameters {#parameters} +#### Parameters -##### code {#code} +##### code [`AuthServerErrorCode`](/references/js/type-aliases/AuthServerErrorCode.md) -##### cause? {#cause} +##### cause? `unknown` -#### Returns {#returns} +#### Returns `MCPAuthAuthServerError` -#### Overrides {#overrides} +#### Overrides [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) -## Properties {#properties} +## Properties -### cause? {#cause} +### cause? ```ts readonly optional cause: unknown; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) *** -### code {#code} +### code ```ts readonly code: AuthServerErrorCode; @@ -58,191 +58,141 @@ readonly code: AuthServerErrorCode; The error code in snake_case format. -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) *** -### message {#message} +### message ```ts message: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) *** -### name {#name} +### name ```ts name: string = 'MCPAuthAuthServerError'; ``` -#### Overrides {#overrides} +#### Overrides [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) *** -### stack? {#stack} +### stack? ```ts optional stack: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) *** -### stackTraceLimit {#stacktracelimit} +### prepareStackTrace()? ```ts -static stackTraceLimit: number; +static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; ``` -The `Error.stackTraceLimit` property specifies the number of stack frames -collected by a stack trace (whether generated by `new Error().stack` or -`Error.captureStackTrace(obj)`). - -The default value is `10` but may be set to any valid JavaScript number. Changes -will affect any stack trace captured _after_ the value has been changed. - -If set to a non-number value, or set to a negative number, stack traces will -not capture any frames. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} +Optional override for formatting stack traces -### toJson() {#tojson} +#### Parameters -```ts -toJson(showCause: boolean): Record; -``` +##### err -Converts the error to a HTTP response friendly JSON format. +`Error` -#### Parameters {#parameters} +##### stackTraces -##### showCause {#showcause} +`CallSite`[] -`boolean` = `false` +#### Returns -Whether to include the cause of the error in the JSON response. -Defaults to `false`. +`any` -#### Returns {#returns} +#### See -`Record`\<`string`, `unknown`\> +https://v8.dev/docs/stack-trace-api#customizing-stack-traces -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) *** -### captureStackTrace() {#capturestacktrace} +### stackTraceLimit ```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Creates a `.stack` property on `targetObject`, which when accessed returns -a string representing the location in the code at which -`Error.captureStackTrace()` was called. - -```js -const myObject = {}; -Error.captureStackTrace(myObject); -myObject.stack; // Similar to `new Error().stack` +static stackTraceLimit: number; ``` -The first line of the trace will be prefixed with -`${myObject.name}: ${myObject.message}`. - -The optional `constructorOpt` argument accepts a function. If given, all frames -above `constructorOpt`, including `constructorOpt`, will be omitted from the -generated stack trace. +#### Inherited from -The `constructorOpt` argument is useful for hiding implementation -details of error generation from the user. For instance: - -```js -function a() { - b(); -} - -function b() { - c(); -} +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) -function c() { - // Create an error without stack trace to avoid calculating the stack trace twice. - const { stackTraceLimit } = Error; - Error.stackTraceLimit = 0; - const error = new Error(); - Error.stackTraceLimit = stackTraceLimit; +## Methods - // Capture the stack trace above function b - Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace - throw error; -} +### toJson() -a(); +```ts +toJson(showCause: boolean): Record; ``` -#### Parameters {#parameters} +Converts the error to a HTTP response friendly JSON format. -##### targetObject {#targetobject} +#### Parameters -`object` +##### showCause -##### constructorOpt? {#constructoropt} +`boolean` = `false` -`Function` +Whether to include the cause of the error in the JSON response. +Defaults to `false`. -#### Returns {#returns} +#### Returns -`void` +`Record`\<`string`, `unknown`\> -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) *** -### prepareStackTrace() {#preparestacktrace} +### captureStackTrace() ```ts -static prepareStackTrace(err: Error, stackTraces: CallSite[]): any; +static captureStackTrace(targetObject: object, constructorOpt?: Function): void; ``` -#### Parameters {#parameters} +Create .stack property on a target object -##### err {#err} +#### Parameters -`Error` +##### targetObject -##### stackTraces {#stacktraces} - -`CallSite`[] +`object` -#### Returns {#returns} +##### constructorOpt? -`any` +`Function` -#### See {#see} +#### Returns -https://v8.dev/docs/stack-trace-api#customizing-stack-traces +`void` -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/docs/references/js/classes/MCPAuthBearerAuthError.md b/docs/references/js/classes/MCPAuthBearerAuthError.md index 9a5b9c6..871e300 100644 --- a/docs/references/js/classes/MCPAuthBearerAuthError.md +++ b/docs/references/js/classes/MCPAuthBearerAuthError.md @@ -6,51 +6,51 @@ sidebar_label: MCPAuthBearerAuthError Error thrown when there is an issue when authenticating with Bearer tokens. -## Extends {#extends} +## Extends - [`MCPAuthError`](/references/js/classes/MCPAuthError.md) -## Constructors {#constructors} +## Constructors -### Constructor {#constructor} +### Constructor ```ts new MCPAuthBearerAuthError(code: BearerAuthErrorCode, cause?: MCPAuthBearerAuthErrorDetails): MCPAuthBearerAuthError; ``` -#### Parameters {#parameters} +#### Parameters -##### code {#code} +##### code [`BearerAuthErrorCode`](/references/js/type-aliases/BearerAuthErrorCode.md) -##### cause? {#cause} +##### cause? [`MCPAuthBearerAuthErrorDetails`](/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md) -#### Returns {#returns} +#### Returns `MCPAuthBearerAuthError` -#### Overrides {#overrides} +#### Overrides [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) -## Properties {#properties} +## Properties -### cause? {#cause} +### cause? ```ts readonly optional cause: MCPAuthBearerAuthErrorDetails; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) *** -### code {#code} +### code ```ts readonly code: BearerAuthErrorCode; @@ -58,191 +58,141 @@ readonly code: BearerAuthErrorCode; The error code in snake_case format. -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) *** -### message {#message} +### message ```ts message: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) *** -### name {#name} +### name ```ts name: string = 'MCPAuthBearerAuthError'; ``` -#### Overrides {#overrides} +#### Overrides [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) *** -### stack? {#stack} +### stack? ```ts optional stack: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) *** -### stackTraceLimit {#stacktracelimit} +### prepareStackTrace()? ```ts -static stackTraceLimit: number; +static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; ``` -The `Error.stackTraceLimit` property specifies the number of stack frames -collected by a stack trace (whether generated by `new Error().stack` or -`Error.captureStackTrace(obj)`). - -The default value is `10` but may be set to any valid JavaScript number. Changes -will affect any stack trace captured _after_ the value has been changed. - -If set to a non-number value, or set to a negative number, stack traces will -not capture any frames. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} +Optional override for formatting stack traces -### toJson() {#tojson} +#### Parameters -```ts -toJson(showCause: boolean): Record; -``` +##### err -Converts the error to a HTTP response friendly JSON format. +`Error` -#### Parameters {#parameters} +##### stackTraces -##### showCause {#showcause} +`CallSite`[] -`boolean` = `false` +#### Returns -Whether to include the cause of the error in the JSON response. -Defaults to `false`. +`any` -#### Returns {#returns} +#### See -`Record`\<`string`, `unknown`\> +https://v8.dev/docs/stack-trace-api#customizing-stack-traces -#### Overrides {#overrides} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) *** -### captureStackTrace() {#capturestacktrace} +### stackTraceLimit ```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Creates a `.stack` property on `targetObject`, which when accessed returns -a string representing the location in the code at which -`Error.captureStackTrace()` was called. - -```js -const myObject = {}; -Error.captureStackTrace(myObject); -myObject.stack; // Similar to `new Error().stack` +static stackTraceLimit: number; ``` -The first line of the trace will be prefixed with -`${myObject.name}: ${myObject.message}`. - -The optional `constructorOpt` argument accepts a function. If given, all frames -above `constructorOpt`, including `constructorOpt`, will be omitted from the -generated stack trace. +#### Inherited from -The `constructorOpt` argument is useful for hiding implementation -details of error generation from the user. For instance: - -```js -function a() { - b(); -} - -function b() { - c(); -} +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) -function c() { - // Create an error without stack trace to avoid calculating the stack trace twice. - const { stackTraceLimit } = Error; - Error.stackTraceLimit = 0; - const error = new Error(); - Error.stackTraceLimit = stackTraceLimit; +## Methods - // Capture the stack trace above function b - Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace - throw error; -} +### toJson() -a(); +```ts +toJson(showCause: boolean): Record; ``` -#### Parameters {#parameters} +Converts the error to a HTTP response friendly JSON format. -##### targetObject {#targetobject} +#### Parameters -`object` +##### showCause -##### constructorOpt? {#constructoropt} +`boolean` = `false` -`Function` +Whether to include the cause of the error in the JSON response. +Defaults to `false`. -#### Returns {#returns} +#### Returns -`void` +`Record`\<`string`, `unknown`\> -#### Inherited from {#inherited-from} +#### Overrides -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) *** -### prepareStackTrace() {#preparestacktrace} +### captureStackTrace() ```ts -static prepareStackTrace(err: Error, stackTraces: CallSite[]): any; +static captureStackTrace(targetObject: object, constructorOpt?: Function): void; ``` -#### Parameters {#parameters} +Create .stack property on a target object -##### err {#err} +#### Parameters -`Error` +##### targetObject -##### stackTraces {#stacktraces} - -`CallSite`[] +`object` -#### Returns {#returns} +##### constructorOpt? -`any` +`Function` -#### See {#see} +#### Returns -https://v8.dev/docs/stack-trace-api#customizing-stack-traces +`void` -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/docs/references/js/classes/MCPAuthConfigError.md b/docs/references/js/classes/MCPAuthConfigError.md index 78a4dba..bc6f5b1 100644 --- a/docs/references/js/classes/MCPAuthConfigError.md +++ b/docs/references/js/classes/MCPAuthConfigError.md @@ -6,55 +6,55 @@ sidebar_label: MCPAuthConfigError Error thrown when there is a configuration issue with mcp-auth. -## Extends {#extends} +## Extends - [`MCPAuthError`](/references/js/classes/MCPAuthError.md) -## Constructors {#constructors} +## Constructors -### Constructor {#constructor} +### Constructor ```ts new MCPAuthConfigError(code: string, message: string): MCPAuthConfigError; ``` -#### Parameters {#parameters} +#### Parameters -##### code {#code} +##### code `string` The error code in snake_case format. -##### message {#message} +##### message `string` A human-readable description of the error. -#### Returns {#returns} +#### Returns `MCPAuthConfigError` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) -## Properties {#properties} +## Properties -### cause? {#cause} +### cause? ```ts optional cause: unknown; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) *** -### code {#code} +### code ```ts readonly code: string; @@ -62,191 +62,141 @@ readonly code: string; The error code in snake_case format. -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) *** -### message {#message} +### message ```ts message: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) *** -### name {#name} +### name ```ts name: string = 'MCPAuthConfigError'; ``` -#### Overrides {#overrides} +#### Overrides [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) *** -### stack? {#stack} +### stack? ```ts optional stack: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) *** -### stackTraceLimit {#stacktracelimit} +### prepareStackTrace()? ```ts -static stackTraceLimit: number; +static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; ``` -The `Error.stackTraceLimit` property specifies the number of stack frames -collected by a stack trace (whether generated by `new Error().stack` or -`Error.captureStackTrace(obj)`). - -The default value is `10` but may be set to any valid JavaScript number. Changes -will affect any stack trace captured _after_ the value has been changed. - -If set to a non-number value, or set to a negative number, stack traces will -not capture any frames. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} +Optional override for formatting stack traces -### toJson() {#tojson} +#### Parameters -```ts -toJson(showCause: boolean): Record; -``` +##### err -Converts the error to a HTTP response friendly JSON format. +`Error` -#### Parameters {#parameters} +##### stackTraces -##### showCause {#showcause} +`CallSite`[] -`boolean` = `false` +#### Returns -Whether to include the cause of the error in the JSON response. -Defaults to `false`. +`any` -#### Returns {#returns} +#### See -`Record`\<`string`, `unknown`\> +https://v8.dev/docs/stack-trace-api#customizing-stack-traces -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) *** -### captureStackTrace() {#capturestacktrace} +### stackTraceLimit ```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Creates a `.stack` property on `targetObject`, which when accessed returns -a string representing the location in the code at which -`Error.captureStackTrace()` was called. - -```js -const myObject = {}; -Error.captureStackTrace(myObject); -myObject.stack; // Similar to `new Error().stack` +static stackTraceLimit: number; ``` -The first line of the trace will be prefixed with -`${myObject.name}: ${myObject.message}`. - -The optional `constructorOpt` argument accepts a function. If given, all frames -above `constructorOpt`, including `constructorOpt`, will be omitted from the -generated stack trace. +#### Inherited from -The `constructorOpt` argument is useful for hiding implementation -details of error generation from the user. For instance: - -```js -function a() { - b(); -} - -function b() { - c(); -} +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) -function c() { - // Create an error without stack trace to avoid calculating the stack trace twice. - const { stackTraceLimit } = Error; - Error.stackTraceLimit = 0; - const error = new Error(); - Error.stackTraceLimit = stackTraceLimit; +## Methods - // Capture the stack trace above function b - Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace - throw error; -} +### toJson() -a(); +```ts +toJson(showCause: boolean): Record; ``` -#### Parameters {#parameters} +Converts the error to a HTTP response friendly JSON format. -##### targetObject {#targetobject} +#### Parameters -`object` +##### showCause -##### constructorOpt? {#constructoropt} +`boolean` = `false` -`Function` +Whether to include the cause of the error in the JSON response. +Defaults to `false`. -#### Returns {#returns} +#### Returns -`void` +`Record`\<`string`, `unknown`\> -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) *** -### prepareStackTrace() {#preparestacktrace} +### captureStackTrace() ```ts -static prepareStackTrace(err: Error, stackTraces: CallSite[]): any; +static captureStackTrace(targetObject: object, constructorOpt?: Function): void; ``` -#### Parameters {#parameters} +Create .stack property on a target object -##### err {#err} +#### Parameters -`Error` +##### targetObject -##### stackTraces {#stacktraces} - -`CallSite`[] +`object` -#### Returns {#returns} +##### constructorOpt? -`any` +`Function` -#### See {#see} +#### Returns -https://v8.dev/docs/stack-trace-api#customizing-stack-traces +`void` -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/docs/references/js/classes/MCPAuthError.md b/docs/references/js/classes/MCPAuthError.md index 40d6dda..3b634b3 100644 --- a/docs/references/js/classes/MCPAuthError.md +++ b/docs/references/js/classes/MCPAuthError.md @@ -8,58 +8,58 @@ Base class for all mcp-auth errors. It provides a standardized way to handle errors related to MCP authentication and authorization. -## Extends {#extends} +## Extends - `Error` -## Extended by {#extended-by} +## Extended by - [`MCPAuthConfigError`](/references/js/classes/MCPAuthConfigError.md) - [`MCPAuthAuthServerError`](/references/js/classes/MCPAuthAuthServerError.md) - [`MCPAuthBearerAuthError`](/references/js/classes/MCPAuthBearerAuthError.md) - [`MCPAuthTokenVerificationError`](/references/js/classes/MCPAuthTokenVerificationError.md) -## Constructors {#constructors} +## Constructors -### Constructor {#constructor} +### Constructor ```ts new MCPAuthError(code: string, message: string): MCPAuthError; ``` -#### Parameters {#parameters} +#### Parameters -##### code {#code} +##### code `string` The error code in snake_case format. -##### message {#message} +##### message `string` A human-readable description of the error. -#### Returns {#returns} +#### Returns `MCPAuthError` -#### Overrides {#overrides} +#### Overrides ```ts Error.constructor ``` -## Properties {#properties} +## Properties -### cause? {#cause} +### cause? ```ts optional cause: unknown; ``` -#### Inherited from {#inherited-from} +#### Inherited from ```ts Error.cause @@ -67,7 +67,7 @@ Error.cause *** -### code {#code} +### code ```ts readonly code: string; @@ -77,13 +77,13 @@ The error code in snake_case format. *** -### message {#message} +### message ```ts message: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from ```ts Error.message @@ -91,13 +91,13 @@ Error.message *** -### name {#name} +### name ```ts name: string = 'MCPAuthError'; ``` -#### Overrides {#overrides} +#### Overrides ```ts Error.name @@ -105,13 +105,13 @@ Error.name *** -### stack? {#stack} +### stack? ```ts optional stack: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from ```ts Error.stack @@ -119,151 +119,101 @@ Error.stack *** -### stackTraceLimit {#stacktracelimit} +### prepareStackTrace()? ```ts -static stackTraceLimit: number; +static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; ``` -The `Error.stackTraceLimit` property specifies the number of stack frames -collected by a stack trace (whether generated by `new Error().stack` or -`Error.captureStackTrace(obj)`). - -The default value is `10` but may be set to any valid JavaScript number. Changes -will affect any stack trace captured _after_ the value has been changed. +Optional override for formatting stack traces -If set to a non-number value, or set to a negative number, stack traces will -not capture any frames. +#### Parameters -#### Inherited from {#inherited-from} - -```ts -Error.stackTraceLimit -``` +##### err -## Methods {#methods} +`Error` -### toJson() {#tojson} +##### stackTraces -```ts -toJson(showCause: boolean): Record; -``` - -Converts the error to a HTTP response friendly JSON format. +`CallSite`[] -#### Parameters {#parameters} +#### Returns -##### showCause {#showcause} +`any` -`boolean` = `false` +#### See -Whether to include the cause of the error in the JSON response. -Defaults to `false`. +https://v8.dev/docs/stack-trace-api#customizing-stack-traces -#### Returns {#returns} +#### Inherited from -`Record`\<`string`, `unknown`\> +```ts +Error.prepareStackTrace +``` *** -### captureStackTrace() {#capturestacktrace} +### stackTraceLimit ```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; +static stackTraceLimit: number; ``` -Creates a `.stack` property on `targetObject`, which when accessed returns -a string representing the location in the code at which -`Error.captureStackTrace()` was called. +#### Inherited from -```js -const myObject = {}; -Error.captureStackTrace(myObject); -myObject.stack; // Similar to `new Error().stack` +```ts +Error.stackTraceLimit ``` -The first line of the trace will be prefixed with -`${myObject.name}: ${myObject.message}`. - -The optional `constructorOpt` argument accepts a function. If given, all frames -above `constructorOpt`, including `constructorOpt`, will be omitted from the -generated stack trace. - -The `constructorOpt` argument is useful for hiding implementation -details of error generation from the user. For instance: - -```js -function a() { - b(); -} +## Methods -function b() { - c(); -} +### toJson() -function c() { - // Create an error without stack trace to avoid calculating the stack trace twice. - const { stackTraceLimit } = Error; - Error.stackTraceLimit = 0; - const error = new Error(); - Error.stackTraceLimit = stackTraceLimit; - - // Capture the stack trace above function b - Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace - throw error; -} - -a(); +```ts +toJson(showCause: boolean): Record; ``` -#### Parameters {#parameters} - -##### targetObject {#targetobject} - -`object` +Converts the error to a HTTP response friendly JSON format. -##### constructorOpt? {#constructoropt} +#### Parameters -`Function` +##### showCause -#### Returns {#returns} +`boolean` = `false` -`void` +Whether to include the cause of the error in the JSON response. +Defaults to `false`. -#### Inherited from {#inherited-from} +#### Returns -```ts -Error.captureStackTrace -``` +`Record`\<`string`, `unknown`\> *** -### prepareStackTrace() {#preparestacktrace} +### captureStackTrace() ```ts -static prepareStackTrace(err: Error, stackTraces: CallSite[]): any; +static captureStackTrace(targetObject: object, constructorOpt?: Function): void; ``` -#### Parameters {#parameters} +Create .stack property on a target object -##### err {#err} +#### Parameters -`Error` - -##### stackTraces {#stacktraces} +##### targetObject -`CallSite`[] +`object` -#### Returns {#returns} +##### constructorOpt? -`any` +`Function` -#### See {#see} +#### Returns -https://v8.dev/docs/stack-trace-api#customizing-stack-traces +`void` -#### Inherited from {#inherited-from} +#### Inherited from ```ts -Error.prepareStackTrace +Error.captureStackTrace ``` diff --git a/docs/references/js/classes/MCPAuthTokenVerificationError.md b/docs/references/js/classes/MCPAuthTokenVerificationError.md index b24e77d..0ff8407 100644 --- a/docs/references/js/classes/MCPAuthTokenVerificationError.md +++ b/docs/references/js/classes/MCPAuthTokenVerificationError.md @@ -6,51 +6,51 @@ sidebar_label: MCPAuthTokenVerificationError Error thrown when there is an issue when verifying tokens. -## Extends {#extends} +## Extends - [`MCPAuthError`](/references/js/classes/MCPAuthError.md) -## Constructors {#constructors} +## Constructors -### Constructor {#constructor} +### Constructor ```ts new MCPAuthTokenVerificationError(code: MCPAuthTokenVerificationErrorCode, cause?: unknown): MCPAuthTokenVerificationError; ``` -#### Parameters {#parameters} +#### Parameters -##### code {#code} +##### code [`MCPAuthTokenVerificationErrorCode`](/references/js/type-aliases/MCPAuthTokenVerificationErrorCode.md) -##### cause? {#cause} +##### cause? `unknown` -#### Returns {#returns} +#### Returns `MCPAuthTokenVerificationError` -#### Overrides {#overrides} +#### Overrides [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`constructor`](/references/js/classes/MCPAuthError.md#constructor) -## Properties {#properties} +## Properties -### cause? {#cause} +### cause? ```ts readonly optional cause: unknown; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`cause`](/references/js/classes/MCPAuthError.md#cause) *** -### code {#code} +### code ```ts readonly code: MCPAuthTokenVerificationErrorCode; @@ -58,191 +58,141 @@ readonly code: MCPAuthTokenVerificationErrorCode; The error code in snake_case format. -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`code`](/references/js/classes/MCPAuthError.md#code) *** -### message {#message} +### message ```ts message: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`message`](/references/js/classes/MCPAuthError.md#message) *** -### name {#name} +### name ```ts name: string = 'MCPAuthTokenVerificationError'; ``` -#### Overrides {#overrides} +#### Overrides [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`name`](/references/js/classes/MCPAuthError.md#name) *** -### stack? {#stack} +### stack? ```ts optional stack: string; ``` -#### Inherited from {#inherited-from} +#### Inherited from [`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stack`](/references/js/classes/MCPAuthError.md#stack) *** -### stackTraceLimit {#stacktracelimit} +### prepareStackTrace()? ```ts -static stackTraceLimit: number; +static optional prepareStackTrace: (err: Error, stackTraces: CallSite[]) => any; ``` -The `Error.stackTraceLimit` property specifies the number of stack frames -collected by a stack trace (whether generated by `new Error().stack` or -`Error.captureStackTrace(obj)`). - -The default value is `10` but may be set to any valid JavaScript number. Changes -will affect any stack trace captured _after_ the value has been changed. - -If set to a non-number value, or set to a negative number, stack traces will -not capture any frames. - -#### Inherited from {#inherited-from} - -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) - -## Methods {#methods} +Optional override for formatting stack traces -### toJson() {#tojson} +#### Parameters -```ts -toJson(showCause: boolean): Record; -``` +##### err -Converts the error to a HTTP response friendly JSON format. +`Error` -#### Parameters {#parameters} +##### stackTraces -##### showCause {#showcause} +`CallSite`[] -`boolean` = `false` +#### Returns -Whether to include the cause of the error in the JSON response. -Defaults to `false`. +`any` -#### Returns {#returns} +#### See -`Record`\<`string`, `unknown`\> +https://v8.dev/docs/stack-trace-api#customizing-stack-traces -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) *** -### captureStackTrace() {#capturestacktrace} +### stackTraceLimit ```ts -static captureStackTrace(targetObject: object, constructorOpt?: Function): void; -``` - -Creates a `.stack` property on `targetObject`, which when accessed returns -a string representing the location in the code at which -`Error.captureStackTrace()` was called. - -```js -const myObject = {}; -Error.captureStackTrace(myObject); -myObject.stack; // Similar to `new Error().stack` +static stackTraceLimit: number; ``` -The first line of the trace will be prefixed with -`${myObject.name}: ${myObject.message}`. - -The optional `constructorOpt` argument accepts a function. If given, all frames -above `constructorOpt`, including `constructorOpt`, will be omitted from the -generated stack trace. +#### Inherited from -The `constructorOpt` argument is useful for hiding implementation -details of error generation from the user. For instance: - -```js -function a() { - b(); -} - -function b() { - c(); -} +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`stackTraceLimit`](/references/js/classes/MCPAuthError.md#stacktracelimit) -function c() { - // Create an error without stack trace to avoid calculating the stack trace twice. - const { stackTraceLimit } = Error; - Error.stackTraceLimit = 0; - const error = new Error(); - Error.stackTraceLimit = stackTraceLimit; +## Methods - // Capture the stack trace above function b - Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace - throw error; -} +### toJson() -a(); +```ts +toJson(showCause: boolean): Record; ``` -#### Parameters {#parameters} +Converts the error to a HTTP response friendly JSON format. -##### targetObject {#targetobject} +#### Parameters -`object` +##### showCause -##### constructorOpt? {#constructoropt} +`boolean` = `false` -`Function` +Whether to include the cause of the error in the JSON response. +Defaults to `false`. -#### Returns {#returns} +#### Returns -`void` +`Record`\<`string`, `unknown`\> -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`toJson`](/references/js/classes/MCPAuthError.md#tojson) *** -### prepareStackTrace() {#preparestacktrace} +### captureStackTrace() ```ts -static prepareStackTrace(err: Error, stackTraces: CallSite[]): any; +static captureStackTrace(targetObject: object, constructorOpt?: Function): void; ``` -#### Parameters {#parameters} +Create .stack property on a target object -##### err {#err} +#### Parameters -`Error` +##### targetObject -##### stackTraces {#stacktraces} - -`CallSite`[] +`object` -#### Returns {#returns} +##### constructorOpt? -`any` +`Function` -#### See {#see} +#### Returns -https://v8.dev/docs/stack-trace-api#customizing-stack-traces +`void` -#### Inherited from {#inherited-from} +#### Inherited from -[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`prepareStackTrace`](/references/js/classes/MCPAuthError.md#preparestacktrace) +[`MCPAuthError`](/references/js/classes/MCPAuthError.md).[`captureStackTrace`](/references/js/classes/MCPAuthError.md#capturestacktrace) diff --git a/docs/references/js/functions/createVerifyJwt.md b/docs/references/js/functions/createVerifyJwt.md index c7126e8..1746416 100644 --- a/docs/references/js/functions/createVerifyJwt.md +++ b/docs/references/js/functions/createVerifyJwt.md @@ -11,9 +11,9 @@ function createVerifyJwt(getKey: JWTVerifyGetKey, options?: JWTVerifyOptions): V Creates a function to verify JWT access tokens using the provided key retrieval function and options. -## Parameters {#parameters} +## Parameters -### getKey {#getkey} +### getKey `JWTVerifyGetKey` @@ -23,7 +23,7 @@ The function to retrieve the key used to verify the JWT. JWTVerifyGetKey for the type definition of the key retrieval function. -### options? {#options} +### options? `JWTVerifyOptions` @@ -33,7 +33,7 @@ Optional JWT verification options. JWTVerifyOptions for the type definition of the options. -## Returns {#returns} +## Returns [`VerifyAccessTokenFunction`](/references/js/type-aliases/VerifyAccessTokenFunction.md) @@ -42,6 +42,6 @@ the token is valid. It requires the JWT to contain the fields `iss`, `client_id` its payload, and it can optionally contain `scope` or `scopes` fields. The function uses the `jose` library under the hood to perform the JWT verification. -## See {#see} +## See [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) for the type definition of the returned function. diff --git a/docs/references/js/functions/fetchServerConfig.md b/docs/references/js/functions/fetchServerConfig.md index 2c9f186..58c8ce8 100644 --- a/docs/references/js/functions/fetchServerConfig.md +++ b/docs/references/js/functions/fetchServerConfig.md @@ -5,7 +5,7 @@ sidebar_label: fetchServerConfig # Function: fetchServerConfig() ```ts -function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; +function fetchServerConfig(issuer: string, config: ServerMetadataConfig): Promise; ``` Fetches the server configuration according to the issuer and authorization server type. @@ -13,27 +13,27 @@ Fetches the server configuration according to the issuer and authorization serve This function automatically determines the well-known URL based on the server type, as OAuth and OpenID Connect servers have different conventions for their metadata endpoints. -## Parameters {#parameters} +## Parameters -### issuer {#issuer} +### issuer `string` The issuer URL of the authorization server. -### config {#config} +### config `ServerMetadataConfig` The configuration object containing the server type and optional transpile function. -## Returns {#returns} +## Returns -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> +`Promise`\<[`ResolvedAuthServerConfig`](/references/js/type-aliases/ResolvedAuthServerConfig.md)\> -A promise that resolves to the server configuration. +A promise that resolves to the static server configuration with fetched metadata. -## See {#see} +## See - [fetchServerConfigByWellKnownUrl](/references/js/functions/fetchServerConfigByWellKnownUrl.md) for the underlying implementation. - [https://www.rfc-editor.org/rfc/rfc8414](https://www.rfc-editor.org/rfc/rfc8414) for the OAuth 2.0 Authorization Server Metadata @@ -41,7 +41,7 @@ specification. - [https://openid.net/specs/openid-connect-discovery-1\_0.html](https://openid.net/specs/openid-connect-discovery-1_0.html) for the OpenID Connect Discovery specification. -## Example {#example} +## Example ```ts import { fetchServerConfig } from 'mcp-auth'; @@ -54,11 +54,11 @@ const oauthConfig = await fetchServerConfig('https://auth.logto.io/oauth', { typ const oidcConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' }); ``` -## Throws {#throws} +## Throws if the fetch operation fails. -## Throws {#throws} +## Throws if the server metadata is invalid or does not match the MCP specification. diff --git a/docs/references/js/functions/fetchServerConfigByWellKnownUrl.md b/docs/references/js/functions/fetchServerConfigByWellKnownUrl.md index 7ab45db..c02019b 100644 --- a/docs/references/js/functions/fetchServerConfigByWellKnownUrl.md +++ b/docs/references/js/functions/fetchServerConfigByWellKnownUrl.md @@ -5,7 +5,7 @@ sidebar_label: fetchServerConfigByWellKnownUrl # Function: fetchServerConfigByWellKnownUrl() ```ts -function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; +function fetchServerConfigByWellKnownUrl(wellKnownUrl: string | URL, config: ServerMetadataConfig): Promise; ``` Fetches the server configuration from the provided well-known URL and validates it against the @@ -15,32 +15,32 @@ If the server metadata does not conform to the expected schema, but you are sure compatible, you can define a `transpileData` function to transform the metadata into the expected format. -## Parameters {#parameters} +## Parameters -### wellKnownUrl {#wellknownurl} +### wellKnownUrl The well-known URL to fetch the server configuration from. This can be a string or a URL object. `string` | `URL` -### config {#config} +### config `ServerMetadataConfig` The configuration object containing the server type and optional transpile function. -## Returns {#returns} +## Returns -`Promise`\<[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md)\> +`Promise`\<[`ResolvedAuthServerConfig`](/references/js/type-aliases/ResolvedAuthServerConfig.md)\> -A promise that resolves to the server configuration. +A promise that resolves to the static server configuration with fetched metadata. -## Throws {#throws} +## Throws if the fetch operation fails. -## Throws {#throws} +## Throws if the server metadata is invalid or does not match the MCP specification. diff --git a/docs/references/js/functions/getIssuer.md b/docs/references/js/functions/getIssuer.md new file mode 100644 index 0000000..701c77b --- /dev/null +++ b/docs/references/js/functions/getIssuer.md @@ -0,0 +1,24 @@ +--- +sidebar_label: getIssuer +--- + +# Function: getIssuer() + +```ts +function getIssuer(config: AuthServerConfig): string; +``` + +Get the issuer URL from an auth server config. + +- Resolved config: extracts from `metadata.issuer` +- Discovery config: returns `issuer` directly + +## Parameters + +### config + +[`AuthServerConfig`](/references/js/type-aliases/AuthServerConfig.md) + +## Returns + +`string` diff --git a/docs/references/js/functions/handleBearerAuth.md b/docs/references/js/functions/handleBearerAuth.md index ddb403e..1b1e42c 100644 --- a/docs/references/js/functions/handleBearerAuth.md +++ b/docs/references/js/functions/handleBearerAuth.md @@ -23,20 +23,20 @@ if not, it responds with an appropriate error message. AuthInfo interface defined in the `@modelcontextprotocol/sdk` module. See the extended interface in this file for details. -## Parameters {#parameters} +## Parameters -### param0 {#param0} +### param0 [`BearerAuthConfig`](/references/js/type-aliases/BearerAuthConfig.md) Configuration for the Bearer auth handler. -## Returns {#returns} +## Returns `RequestHandler` A middleware function for Express that handles Bearer auth. -## See {#see} +## See [BearerAuthConfig](/references/js/type-aliases/BearerAuthConfig.md) for the configuration options. diff --git a/docs/references/js/type-aliases/AuthServerConfig.md b/docs/references/js/type-aliases/AuthServerConfig.md index 8166bf3..42f777a 100644 --- a/docs/references/js/type-aliases/AuthServerConfig.md +++ b/docs/references/js/type-aliases/AuthServerConfig.md @@ -5,47 +5,13 @@ sidebar_label: AuthServerConfig # Type Alias: AuthServerConfig ```ts -type AuthServerConfig = { - metadata: CamelCaseAuthorizationServerMetadata; - type: AuthServerType; -}; +type AuthServerConfig = + | ResolvedAuthServerConfig + | AuthServerDiscoveryConfig; ``` Configuration for the remote authorization server integrated with the MCP server. -## Properties {#properties} - -### metadata {#metadata} - -```ts -metadata: CamelCaseAuthorizationServerMetadata; -``` - -The metadata of the authorization server, which should conform to the MCP specification -(based on OAuth 2.0 Authorization Server Metadata). - -This metadata is typically fetched from the server's well-known endpoint (OAuth 2.0 -Authorization Server Metadata or OpenID Connect Discovery); it can also be provided -directly in the configuration if the server does not support such endpoints. - -**Note:** The metadata should be in camelCase format as per preferred by the mcp-auth -library. - -#### See {#see} - - - [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) - -*** - -### type {#type} - -```ts -type: AuthServerType; -``` - -The type of the authorization server. - -#### See {#see} - -[AuthServerType](/references/js/type-aliases/AuthServerType.md) for the possible values. +Can be either: +- **Resolved**: Contains `metadata` - no network request needed +- **Discovery**: Contains only `issuer` and `type` - metadata fetched on-demand via discovery diff --git a/docs/references/js/type-aliases/AuthServerConfigError.md b/docs/references/js/type-aliases/AuthServerConfigError.md index 05371c1..926e985 100644 --- a/docs/references/js/type-aliases/AuthServerConfigError.md +++ b/docs/references/js/type-aliases/AuthServerConfigError.md @@ -14,9 +14,9 @@ type AuthServerConfigError = { Represents an error that occurs during the validation of the authorization server metadata. -## Properties {#properties} +## Properties -### cause? {#cause} +### cause? ```ts optional cause: Error; @@ -26,7 +26,7 @@ An optional cause of the error, typically an instance of `Error` that provides m *** -### code {#code} +### code ```ts code: AuthServerConfigErrorCode; @@ -36,7 +36,7 @@ The code representing the specific validation error. *** -### description {#description} +### description ```ts description: string; diff --git a/docs/references/js/type-aliases/AuthServerConfigWarning.md b/docs/references/js/type-aliases/AuthServerConfigWarning.md index f093e35..42a33f7 100644 --- a/docs/references/js/type-aliases/AuthServerConfigWarning.md +++ b/docs/references/js/type-aliases/AuthServerConfigWarning.md @@ -13,9 +13,9 @@ type AuthServerConfigWarning = { Represents a warning that occurs during the validation of the authorization server metadata. -## Properties {#properties} +## Properties -### code {#code} +### code ```ts code: AuthServerConfigWarningCode; @@ -25,7 +25,7 @@ The code representing the specific validation warning. *** -### description {#description} +### description ```ts description: string; diff --git a/docs/references/js/type-aliases/AuthServerDiscoveryConfig.md b/docs/references/js/type-aliases/AuthServerDiscoveryConfig.md new file mode 100644 index 0000000..2e99b93 --- /dev/null +++ b/docs/references/js/type-aliases/AuthServerDiscoveryConfig.md @@ -0,0 +1,59 @@ +--- +sidebar_label: AuthServerDiscoveryConfig +--- + +# Type Alias: AuthServerDiscoveryConfig + +```ts +type AuthServerDiscoveryConfig = { + issuer: string; + type: AuthServerType; +}; +``` + +Discovery configuration for the remote authorization server. + +Use this when you want the metadata to be fetched on-demand via discovery when first needed. +This is useful for edge runtimes like Cloudflare Workers where top-level async fetch +is not allowed. + +## Example + +```typescript +const mcpAuth = new MCPAuth({ + protectedResources: { + metadata: { + resource: 'https://api.example.com', + authorizationServers: [ + { issuer: 'https://auth.logto.io/oidc', type: 'oidc' } + ], + scopesSupported: ['read', 'write'], + }, + }, +}); +``` + +## Properties + +### issuer + +```ts +issuer: string; +``` + +The issuer URL of the authorization server. The metadata will be fetched from the +well-known endpoint derived from this issuer. + +*** + +### type + +```ts +type: AuthServerType; +``` + +The type of the authorization server. + +#### See + +[AuthServerType](/references/js/type-aliases/AuthServerType.md) for the possible values. diff --git a/docs/references/js/type-aliases/AuthServerModeConfig.md b/docs/references/js/type-aliases/AuthServerModeConfig.md index da4c827..6cb5594 100644 --- a/docs/references/js/type-aliases/AuthServerModeConfig.md +++ b/docs/references/js/type-aliases/AuthServerModeConfig.md @@ -12,13 +12,13 @@ type AuthServerModeConfig = { Configuration for the legacy, MCP server as authorization server mode. -## Deprecated {#deprecated} +## Deprecated Use `ResourceServerModeConfig` config instead. -## Properties {#properties} +## Properties -### ~~server~~ {#server} +### ~~server~~ ```ts server: AuthServerConfig; @@ -26,6 +26,6 @@ server: AuthServerConfig; The single authorization server configuration. -#### Deprecated {#deprecated} +#### Deprecated Use `protectedResources` config instead. diff --git a/docs/references/js/type-aliases/AuthorizationServerMetadata.md b/docs/references/js/type-aliases/AuthorizationServerMetadata.md index b07bdc2..b903d81 100644 --- a/docs/references/js/type-aliases/AuthorizationServerMetadata.md +++ b/docs/references/js/type-aliases/AuthorizationServerMetadata.md @@ -5,235 +5,11 @@ sidebar_label: AuthorizationServerMetadata # Type Alias: AuthorizationServerMetadata ```ts -type AuthorizationServerMetadata = { - authorization_endpoint: string; - code_challenge_methods_supported?: string[]; - grant_types_supported?: string[]; - introspection_endpoint?: string; - introspection_endpoint_auth_methods_supported?: string[]; - introspection_endpoint_auth_signing_alg_values_supported?: string[]; - issuer: string; - jwks_uri?: string; - op_policy_uri?: string; - op_tos_uri?: string; - registration_endpoint?: string; - response_modes_supported?: string[]; - response_types_supported: string[]; - revocation_endpoint?: string; - revocation_endpoint_auth_methods_supported?: string[]; - revocation_endpoint_auth_signing_alg_values_supported?: string[]; - scopes_supported?: string[]; - service_documentation?: string; - token_endpoint: string; - token_endpoint_auth_methods_supported?: string[]; - token_endpoint_auth_signing_alg_values_supported?: string[]; - ui_locales_supported?: string[]; - userinfo_endpoint?: string; -}; +type AuthorizationServerMetadata = z.infer; ``` Schema for OAuth 2.0 Authorization Server Metadata as defined in RFC 8414. -## Type declaration {#type-declaration} - -### authorization\_endpoint {#authorization-endpoint} - -```ts -authorization_endpoint: string; -``` - -URL of the authorization server's authorization endpoint [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -This is REQUIRED unless no grant types are supported that use the authorization endpoint. - -#### See {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.1 - -### code\_challenge\_methods\_supported? {#code-challenge-methods-supported} - -```ts -optional code_challenge_methods_supported: string[]; -``` - -JSON array containing a list of Proof Key for Code Exchange (PKCE) -[[RFC7636](https://www.rfc-editor.org/rfc/rfc7636)] code challenge methods supported by this -authorization server. - -### grant\_types\_supported? {#grant-types-supported} - -```ts -optional grant_types_supported: string[]; -``` - -JSON array containing a list of the OAuth 2.0 grant type values that this authorization server -supports. The array values used are the same as those used with the `grant_types` parameter -defined by "OAuth 2.0 Dynamic Client Registration Protocol" [[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. -If omitted, the default value is `["authorization_code", "implicit"]`. - -### introspection\_endpoint? {#introspection-endpoint} - -```ts -optional introspection_endpoint: string; -``` - -URL of the authorization server's OAuth 2.0 introspection endpoint -[[RFC7662](https://www.rfc-editor.org/rfc/rfc7662)]. - -### introspection\_endpoint\_auth\_methods\_supported? {#introspection-endpoint-auth-methods-supported} - -```ts -optional introspection_endpoint_auth_methods_supported: string[]; -``` - -### introspection\_endpoint\_auth\_signing\_alg\_values\_supported? {#introspection-endpoint-auth-signing-alg-values-supported} - -```ts -optional introspection_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -The authorization server's issuer identifier, which is a URL that uses the `https` scheme and -has no query or fragment components. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -URL of the authorization server's JWK Set [[JWK](https://www.rfc-editor.org/rfc/rfc8414.html#ref-JWK)] -document. The referenced document contains the signing key(s) the client uses to validate -signatures from the authorization server. This URL MUST use the `https` scheme. - -### op\_policy\_uri? {#op-policy-uri} - -```ts -optional op_policy_uri: string; -``` - -### op\_tos\_uri? {#op-tos-uri} - -```ts -optional op_tos_uri: string; -``` - -### registration\_endpoint? {#registration-endpoint} - -```ts -optional registration_endpoint: string; -``` - -URL of the authorization server's OAuth 2.0 Dynamic Client Registration endpoint -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### response\_modes\_supported? {#response-modes-supported} - -```ts -optional response_modes_supported: string[]; -``` - -JSON array containing a list of the OAuth 2.0 `response_mode` values that this -authorization server supports, as specified in "OAuth 2.0 Multiple Response -Type Encoding Practices" -[[OAuth.Responses](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Responses)]. - -If omitted, the default is `["query", "fragment"]`. The response mode value `"form_post"` is -also defined in "OAuth 2.0 Form Post Response Mode" -[[OAuth.FormPost](https://datatracker.ietf.org/doc/html/rfc8414#ref-OAuth.Post)]. - -### response\_types\_supported {#response-types-supported} - -```ts -response_types_supported: string[]; -``` - -JSON array containing a list of the OAuth 2.0 `response_type` values that this authorization -server supports. The array values used are the same as those used with the `response_types` -parameter defined by "OAuth 2.0 Dynamic Client Registration Protocol" -[[RFC7591](https://www.rfc-editor.org/rfc/rfc7591)]. - -### revocation\_endpoint? {#revocation-endpoint} - -```ts -optional revocation_endpoint: string; -``` - -URL of the authorization server's OAuth 2.0 revocation endpoint -[[RFC7009](https://www.rfc-editor.org/rfc/rfc7009)]. - -### revocation\_endpoint\_auth\_methods\_supported? {#revocation-endpoint-auth-methods-supported} - -```ts -optional revocation_endpoint_auth_methods_supported: string[]; -``` - -### revocation\_endpoint\_auth\_signing\_alg\_values\_supported? {#revocation-endpoint-auth-signing-alg-values-supported} - -```ts -optional revocation_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### scopes\_supported? {#scopes-supported} - -```ts -optional scopes_supported: string[]; -``` - -JSON array containing a list of the OAuth 2.0 `scope` values that this authorization server -supports. -[[RFC8414](https://datatracker.ietf.org/doc/html/rfc8414#section-2)] - -### service\_documentation? {#service-documentation} - -```ts -optional service_documentation: string; -``` - -### token\_endpoint {#token-endpoint} - -```ts -token_endpoint: string; -``` - -URL of the authorization server's token endpoint [[RFC6749](https://rfc-editor.org/rfc/rfc6749)]. -This is REQUIRED unless only the implicit grant type is supported. - -#### See {#see} - -https://rfc-editor.org/rfc/rfc6749#section-3.2 - -### token\_endpoint\_auth\_methods\_supported? {#token-endpoint-auth-methods-supported} - -```ts -optional token_endpoint_auth_methods_supported: string[]; -``` - -### token\_endpoint\_auth\_signing\_alg\_values\_supported? {#token-endpoint-auth-signing-alg-values-supported} - -```ts -optional token_endpoint_auth_signing_alg_values_supported: string[]; -``` - -### ui\_locales\_supported? {#ui-locales-supported} - -```ts -optional ui_locales_supported: string[]; -``` - -### userinfo\_endpoint? {#userinfo-endpoint} - -```ts -optional userinfo_endpoint: string; -``` - -URL of the OpenID Connect [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). -This endpoint is used to retrieve information about the authenticated user. - -## See {#see} +## See https://datatracker.ietf.org/doc/html/rfc8414 diff --git a/docs/references/js/type-aliases/BearerAuthConfig.md b/docs/references/js/type-aliases/BearerAuthConfig.md index cfb0f36..82bb23e 100644 --- a/docs/references/js/type-aliases/BearerAuthConfig.md +++ b/docs/references/js/type-aliases/BearerAuthConfig.md @@ -16,9 +16,9 @@ type BearerAuthConfig = { }; ``` -## Properties {#properties} +## Properties -### audience? {#audience} +### audience? ```ts optional audience: string; @@ -30,13 +30,13 @@ The expected audience of the access token (`aud` claim). This is typically the r **Note:** If your authorization server does not support Resource Indicators (RFC 8707), you can omit this field since the audience may not be relevant. -#### See {#see} +#### See https://datatracker.ietf.org/doc/html/rfc8707 *** -### issuer {#issuer} +### issuer ```ts issuer: @@ -51,13 +51,13 @@ If a string is provided, it will be used as the expected issuer value for direct If a function is provided, it should validate the issuer according to the rules in [ValidateIssuerFunction](/references/js/type-aliases/ValidateIssuerFunction.md). -#### See {#see} +#### See [ValidateIssuerFunction](/references/js/type-aliases/ValidateIssuerFunction.md) for more details about the validation function. *** -### requiredScopes? {#requiredscopes} +### requiredScopes? ```ts optional requiredScopes: string[]; @@ -73,7 +73,7 @@ if available. *** -### resource? {#resource} +### resource? ```ts optional resource: string; @@ -85,7 +85,7 @@ It's required when using the handler with a `protectedResources` configuration. *** -### showErrorDetails? {#showerrordetails} +### showErrorDetails? ```ts optional showErrorDetails: boolean; @@ -95,7 +95,7 @@ Whether to show detailed error information in the response. This is useful for d during development, but should be disabled in production to avoid leaking sensitive information. -#### Default {#default} +#### Default ```ts false @@ -103,7 +103,7 @@ false *** -### verifyAccessToken {#verifyaccesstoken} +### verifyAccessToken ```ts verifyAccessToken: VerifyAccessTokenFunction; @@ -114,6 +114,6 @@ Function type for verifying an access token. This function should throw an [MCPAuthTokenVerificationError](/references/js/classes/MCPAuthTokenVerificationError.md) if the token is invalid, or return an AuthInfo object if the token is valid. -#### See {#see} +#### See [VerifyAccessTokenFunction](/references/js/type-aliases/VerifyAccessTokenFunction.md) for more details. diff --git a/docs/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md b/docs/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md index b2d0efa..dcb6f9f 100644 --- a/docs/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md +++ b/docs/references/js/type-aliases/CamelCaseAuthorizationServerMetadata.md @@ -5,175 +5,11 @@ sidebar_label: CamelCaseAuthorizationServerMetadata # Type Alias: CamelCaseAuthorizationServerMetadata ```ts -type CamelCaseAuthorizationServerMetadata = { - authorizationEndpoint: string; - codeChallengeMethodsSupported?: string[]; - grantTypesSupported?: string[]; - introspectionEndpoint?: string; - introspectionEndpointAuthMethodsSupported?: string[]; - introspectionEndpointAuthSigningAlgValuesSupported?: string[]; - issuer: string; - jwksUri?: string; - opPolicyUri?: string; - opTosUri?: string; - registrationEndpoint?: string; - responseModesSupported?: string[]; - responseTypesSupported: string[]; - revocationEndpoint?: string; - revocationEndpointAuthMethodsSupported?: string[]; - revocationEndpointAuthSigningAlgValuesSupported?: string[]; - scopesSupported?: string[]; - serviceDocumentation?: string; - tokenEndpoint: string; - tokenEndpointAuthMethodsSupported?: string[]; - tokenEndpointAuthSigningAlgValuesSupported?: string[]; - uiLocalesSupported?: string[]; - userinfoEndpoint?: string; -}; +type CamelCaseAuthorizationServerMetadata = z.infer; ``` The camelCase version of the OAuth 2.0 Authorization Server Metadata type. -## Type declaration {#type-declaration} - -### authorizationEndpoint {#authorizationendpoint} - -```ts -authorizationEndpoint: string; -``` - -### codeChallengeMethodsSupported? {#codechallengemethodssupported} - -```ts -optional codeChallengeMethodsSupported: string[]; -``` - -### grantTypesSupported? {#granttypessupported} - -```ts -optional grantTypesSupported: string[]; -``` - -### introspectionEndpoint? {#introspectionendpoint} - -```ts -optional introspectionEndpoint: string; -``` - -### introspectionEndpointAuthMethodsSupported? {#introspectionendpointauthmethodssupported} - -```ts -optional introspectionEndpointAuthMethodsSupported: string[]; -``` - -### introspectionEndpointAuthSigningAlgValuesSupported? {#introspectionendpointauthsigningalgvaluessupported} - -```ts -optional introspectionEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### issuer {#issuer} - -```ts -issuer: string; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### opPolicyUri? {#oppolicyuri} - -```ts -optional opPolicyUri: string; -``` - -### opTosUri? {#optosuri} - -```ts -optional opTosUri: string; -``` - -### registrationEndpoint? {#registrationendpoint} - -```ts -optional registrationEndpoint: string; -``` - -### responseModesSupported? {#responsemodessupported} - -```ts -optional responseModesSupported: string[]; -``` - -### responseTypesSupported {#responsetypessupported} - -```ts -responseTypesSupported: string[]; -``` - -### revocationEndpoint? {#revocationendpoint} - -```ts -optional revocationEndpoint: string; -``` - -### revocationEndpointAuthMethodsSupported? {#revocationendpointauthmethodssupported} - -```ts -optional revocationEndpointAuthMethodsSupported: string[]; -``` - -### revocationEndpointAuthSigningAlgValuesSupported? {#revocationendpointauthsigningalgvaluessupported} - -```ts -optional revocationEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### scopesSupported? {#scopessupported} - -```ts -optional scopesSupported: string[]; -``` - -### serviceDocumentation? {#servicedocumentation} - -```ts -optional serviceDocumentation: string; -``` - -### tokenEndpoint {#tokenendpoint} - -```ts -tokenEndpoint: string; -``` - -### tokenEndpointAuthMethodsSupported? {#tokenendpointauthmethodssupported} - -```ts -optional tokenEndpointAuthMethodsSupported: string[]; -``` - -### tokenEndpointAuthSigningAlgValuesSupported? {#tokenendpointauthsigningalgvaluessupported} - -```ts -optional tokenEndpointAuthSigningAlgValuesSupported: string[]; -``` - -### uiLocalesSupported? {#uilocalessupported} - -```ts -optional uiLocalesSupported: string[]; -``` - -### userinfoEndpoint? {#userinfoendpoint} - -```ts -optional userinfoEndpoint: string; -``` - -## See {#see} +## See [AuthorizationServerMetadata](/references/js/type-aliases/AuthorizationServerMetadata.md) for the original type and field information. diff --git a/docs/references/js/type-aliases/CamelCaseProtectedResourceMetadata.md b/docs/references/js/type-aliases/CamelCaseProtectedResourceMetadata.md index 390e9de..b23a29f 100644 --- a/docs/references/js/type-aliases/CamelCaseProtectedResourceMetadata.md +++ b/docs/references/js/type-aliases/CamelCaseProtectedResourceMetadata.md @@ -5,119 +5,11 @@ sidebar_label: CamelCaseProtectedResourceMetadata # Type Alias: CamelCaseProtectedResourceMetadata ```ts -type CamelCaseProtectedResourceMetadata = { - authorizationDetailsTypesSupported?: string[]; - authorizationServers?: string[]; - bearerMethodsSupported?: string[]; - dpopBoundAccessTokensRequired?: boolean; - dpopSigningAlgValuesSupported?: string[]; - jwksUri?: string; - resource: string; - resourceDocumentation?: string; - resourceName?: string; - resourcePolicyUri?: string; - resourceSigningAlgValuesSupported?: string[]; - resourceTosUri?: string; - scopesSupported?: string[]; - signedMetadata?: string; - tlsClientCertificateBoundAccessTokens?: boolean; -}; +type CamelCaseProtectedResourceMetadata = z.infer; ``` The camelCase version of the OAuth 2.0 Protected Resource Metadata type. -## Type declaration {#type-declaration} - -### authorizationDetailsTypesSupported? {#authorizationdetailstypessupported} - -```ts -optional authorizationDetailsTypesSupported: string[]; -``` - -### authorizationServers? {#authorizationservers} - -```ts -optional authorizationServers: string[]; -``` - -### bearerMethodsSupported? {#bearermethodssupported} - -```ts -optional bearerMethodsSupported: string[]; -``` - -### dpopBoundAccessTokensRequired? {#dpopboundaccesstokensrequired} - -```ts -optional dpopBoundAccessTokensRequired: boolean; -``` - -### dpopSigningAlgValuesSupported? {#dpopsigningalgvaluessupported} - -```ts -optional dpopSigningAlgValuesSupported: string[]; -``` - -### jwksUri? {#jwksuri} - -```ts -optional jwksUri: string; -``` - -### resource {#resource} - -```ts -resource: string; -``` - -### resourceDocumentation? {#resourcedocumentation} - -```ts -optional resourceDocumentation: string; -``` - -### resourceName? {#resourcename} - -```ts -optional resourceName: string; -``` - -### resourcePolicyUri? {#resourcepolicyuri} - -```ts -optional resourcePolicyUri: string; -``` - -### resourceSigningAlgValuesSupported? {#resourcesigningalgvaluessupported} - -```ts -optional resourceSigningAlgValuesSupported: string[]; -``` - -### resourceTosUri? {#resourcetosuri} - -```ts -optional resourceTosUri: string; -``` - -### scopesSupported? {#scopessupported} - -```ts -optional scopesSupported: string[]; -``` - -### signedMetadata? {#signedmetadata} - -```ts -optional signedMetadata: string; -``` - -### tlsClientCertificateBoundAccessTokens? {#tlsclientcertificateboundaccesstokens} - -```ts -optional tlsClientCertificateBoundAccessTokens: boolean; -``` - -## See {#see} +## See [ProtectedResourceMetadata](/references/js/type-aliases/ProtectedResourceMetadata.md) for the original type and field information. diff --git a/docs/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md b/docs/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md index 9961d48..d3ae27f 100644 --- a/docs/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md +++ b/docs/references/js/type-aliases/MCPAuthBearerAuthErrorDetails.md @@ -14,9 +14,9 @@ type MCPAuthBearerAuthErrorDetails = { }; ``` -## Properties {#properties} +## Properties -### actual? {#actual} +### actual? ```ts optional actual: unknown; @@ -24,7 +24,7 @@ optional actual: unknown; *** -### cause? {#cause} +### cause? ```ts optional cause: unknown; @@ -32,7 +32,7 @@ optional cause: unknown; *** -### expected? {#expected} +### expected? ```ts optional expected: unknown; @@ -40,7 +40,7 @@ optional expected: unknown; *** -### missingScopes? {#missingscopes} +### missingScopes? ```ts optional missingScopes: string[]; @@ -48,7 +48,7 @@ optional missingScopes: string[]; *** -### uri? {#uri} +### uri? ```ts optional uri: URL; diff --git a/docs/references/js/type-aliases/ProtectedResourceMetadata.md b/docs/references/js/type-aliases/ProtectedResourceMetadata.md index fd705f7..3910f56 100644 --- a/docs/references/js/type-aliases/ProtectedResourceMetadata.md +++ b/docs/references/js/type-aliases/ProtectedResourceMetadata.md @@ -5,153 +5,7 @@ sidebar_label: ProtectedResourceMetadata # Type Alias: ProtectedResourceMetadata ```ts -type ProtectedResourceMetadata = { - authorization_details_types_supported?: string[]; - authorization_servers?: string[]; - bearer_methods_supported?: string[]; - dpop_bound_access_tokens_required?: boolean; - dpop_signing_alg_values_supported?: string[]; - jwks_uri?: string; - resource: string; - resource_documentation?: string; - resource_name?: string; - resource_policy_uri?: string; - resource_signing_alg_values_supported?: string[]; - resource_tos_uri?: string; - scopes_supported?: string[]; - signed_metadata?: string; - tls_client_certificate_bound_access_tokens?: boolean; -}; +type ProtectedResourceMetadata = z.infer; ``` Schema for OAuth 2.0 Protected Resource Metadata. - -## Type declaration {#type-declaration} - -### authorization\_details\_types\_supported? {#authorization-details-types-supported} - -```ts -optional authorization_details_types_supported: string[]; -``` - -Authorization details type values supported when using the authorization_details request parameter. - -### authorization\_servers? {#authorization-servers} - -```ts -optional authorization_servers: string[]; -``` - -List of OAuth authorization server issuer identifiers that can be used with this protected resource. - -### bearer\_methods\_supported? {#bearer-methods-supported} - -```ts -optional bearer_methods_supported: string[]; -``` - -Supported methods for sending OAuth 2.0 bearer tokens. Values: ["header", "body", "query"]. - -### dpop\_bound\_access\_tokens\_required? {#dpop-bound-access-tokens-required} - -```ts -optional dpop_bound_access_tokens_required: boolean; -``` - -Whether the protected resource always requires DPoP-bound access tokens. - -### dpop\_signing\_alg\_values\_supported? {#dpop-signing-alg-values-supported} - -```ts -optional dpop_signing_alg_values_supported: string[]; -``` - -JWS algorithms supported for validating DPoP proof JWTs. - -### jwks\_uri? {#jwks-uri} - -```ts -optional jwks_uri: string; -``` - -URL of the protected resource's JSON Web Key (JWK) Set document. This document contains the public keys -that can be used to verify digital signatures of responses or data returned by this protected resource. -This differs from the authorization server's jwks_uri which is used for token validation. When the protected -resource signs its responses, clients can fetch these public keys to verify the authenticity and integrity -of the received data. - -### resource {#resource} - -```ts -resource: string; -``` - -The protected resource's resource identifier. - -### resource\_documentation? {#resource-documentation} - -```ts -optional resource_documentation: string; -``` - -URL containing developer documentation for using the protected resource. - -### resource\_name? {#resource-name} - -```ts -optional resource_name: string; -``` - -Human-readable name of the protected resource for display to end users. - -### resource\_policy\_uri? {#resource-policy-uri} - -```ts -optional resource_policy_uri: string; -``` - -URL containing information about the protected resource's data usage requirements. - -### resource\_signing\_alg\_values\_supported? {#resource-signing-alg-values-supported} - -```ts -optional resource_signing_alg_values_supported: string[]; -``` - -JWS signing algorithms supported by the protected resource for signing resource responses. - -### resource\_tos\_uri? {#resource-tos-uri} - -```ts -optional resource_tos_uri: string; -``` - -URL containing the protected resource's terms of service. - -### scopes\_supported? {#scopes-supported} - -```ts -optional scopes_supported: string[]; -``` - -List of scope values used in authorization requests to access this protected resource. - -### signed\_metadata? {#signed-metadata} - -```ts -optional signed_metadata: string; -``` - -A signed JWT containing metadata parameters as claims. The JWT must be signed using JWS and include -an 'iss' claim. This field provides a way to cryptographically verify the authenticity of the metadata -itself. The signature can be verified using the public keys available at the `jwks_uri` endpoint. -When present, the values in this signed metadata take precedence over the corresponding plain -JSON values in this metadata document. This helps prevent tampering with the resource metadata. - -### tls\_client\_certificate\_bound\_access\_tokens? {#tls-client-certificate-bound-access-tokens} - -```ts -optional tls_client_certificate_bound_access_tokens: boolean; -``` - -Whether the protected resource supports mutual-TLS client certificate-bound access tokens. diff --git a/docs/references/js/type-aliases/ResolvedAuthServerConfig.md b/docs/references/js/type-aliases/ResolvedAuthServerConfig.md new file mode 100644 index 0000000..d4ef3de --- /dev/null +++ b/docs/references/js/type-aliases/ResolvedAuthServerConfig.md @@ -0,0 +1,54 @@ +--- +sidebar_label: ResolvedAuthServerConfig +--- + +# Type Alias: ResolvedAuthServerConfig + +```ts +type ResolvedAuthServerConfig = { + metadata: CamelCaseAuthorizationServerMetadata; + type: AuthServerType; +}; +``` + +Resolved configuration for the remote authorization server with metadata. + +Use this when the metadata is already available, either hardcoded or fetched beforehand +via `fetchServerConfig()`. + +## Properties + +### metadata + +```ts +metadata: CamelCaseAuthorizationServerMetadata; +``` + +The metadata of the authorization server, which should conform to the MCP specification +(based on OAuth 2.0 Authorization Server Metadata). + +This metadata is typically fetched from the server's well-known endpoint (OAuth 2.0 +Authorization Server Metadata or OpenID Connect Discovery); it can also be provided +directly in the configuration if the server does not support such endpoints. + +**Note:** The metadata should be in camelCase format as per preferred by the mcp-auth +library. + +#### See + + - [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) + - [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) + +*** + +### type + +```ts +type: AuthServerType; +``` + +The type of the authorization server. + +#### See + +[AuthServerType](/references/js/type-aliases/AuthServerType.md) for the possible values. diff --git a/docs/references/js/type-aliases/ResourceServerModeConfig.md b/docs/references/js/type-aliases/ResourceServerModeConfig.md index a87ce1b..465d870 100644 --- a/docs/references/js/type-aliases/ResourceServerModeConfig.md +++ b/docs/references/js/type-aliases/ResourceServerModeConfig.md @@ -12,9 +12,9 @@ type ResourceServerModeConfig = { Configuration for the MCP server as resource server mode. -## Properties {#properties} +## Properties -### protectedResources {#protectedresources} +### protectedResources ```ts protectedResources: ResourceServerConfig | ResourceServerConfig[]; diff --git a/docs/references/js/type-aliases/ValidateIssuerFunction.md b/docs/references/js/type-aliases/ValidateIssuerFunction.md index b6f1d9f..8f84991 100644 --- a/docs/references/js/type-aliases/ValidateIssuerFunction.md +++ b/docs/references/js/type-aliases/ValidateIssuerFunction.md @@ -16,16 +16,16 @@ is not valid. The issuer should be validated against: 1. The authorization servers configured in MCP-Auth's auth server metadata 2. The authorization servers listed in the protected resource's metadata -## Parameters {#parameters} +## Parameters -### tokenIssuer {#tokenissuer} +### tokenIssuer `string` -## Returns {#returns} +## Returns `void` -## Throws {#throws} +## Throws When the issuer is not recognized or invalid. diff --git a/docs/references/js/type-aliases/VerifyAccessTokenFunction.md b/docs/references/js/type-aliases/VerifyAccessTokenFunction.md index 2bb7325..625cd96 100644 --- a/docs/references/js/type-aliases/VerifyAccessTokenFunction.md +++ b/docs/references/js/type-aliases/VerifyAccessTokenFunction.md @@ -24,15 +24,15 @@ by the handler: - `aud` (audience) - `scope` (scopes) -## Parameters {#parameters} +## Parameters -### token {#token} +### token `string` The access token string to verify. -## Returns {#returns} +## Returns `MaybePromise`\<`AuthInfo`\> diff --git a/docs/references/js/variables/authorizationServerMetadataSchema.md b/docs/references/js/variables/authorizationServerMetadataSchema.md index 2b10818..813b8ba 100644 --- a/docs/references/js/variables/authorizationServerMetadataSchema.md +++ b/docs/references/js/variables/authorizationServerMetadataSchema.md @@ -5,11 +5,35 @@ sidebar_label: authorizationServerMetadataSchema # Variable: authorizationServerMetadataSchema ```ts -const authorizationServerMetadataSchema: ZodObject; +const authorizationServerMetadataSchema: ZodObject<{ + authorization_endpoint: ZodString; + code_challenge_methods_supported: ZodOptional>; + grant_types_supported: ZodOptional>; + introspection_endpoint: ZodOptional; + introspection_endpoint_auth_methods_supported: ZodOptional>; + introspection_endpoint_auth_signing_alg_values_supported: ZodOptional>; + issuer: ZodString; + jwks_uri: ZodOptional; + op_policy_uri: ZodOptional; + op_tos_uri: ZodOptional; + registration_endpoint: ZodOptional; + response_modes_supported: ZodOptional>; + response_types_supported: ZodArray; + revocation_endpoint: ZodOptional; + revocation_endpoint_auth_methods_supported: ZodOptional>; + revocation_endpoint_auth_signing_alg_values_supported: ZodOptional>; + scopes_supported: ZodOptional>; + service_documentation: ZodOptional; + token_endpoint: ZodString; + token_endpoint_auth_methods_supported: ZodOptional>; + token_endpoint_auth_signing_alg_values_supported: ZodOptional>; + ui_locales_supported: ZodOptional>; + userinfo_endpoint: ZodOptional; +}, $strip>; ``` Zod schema for OAuth 2.0 Authorization Server Metadata as defined in RFC 8414. -## See {#see} +## See https://datatracker.ietf.org/doc/html/rfc8414 diff --git a/docs/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md b/docs/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md index daaa358..e4a9b33 100644 --- a/docs/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md +++ b/docs/references/js/variables/camelCaseAuthorizationServerMetadataSchema.md @@ -5,11 +5,35 @@ sidebar_label: camelCaseAuthorizationServerMetadataSchema # Variable: camelCaseAuthorizationServerMetadataSchema ```ts -const camelCaseAuthorizationServerMetadataSchema: ZodObject; +const camelCaseAuthorizationServerMetadataSchema: ZodObject<{ + authorizationEndpoint: ZodString; + codeChallengeMethodsSupported: ZodOptional>; + grantTypesSupported: ZodOptional>; + introspectionEndpoint: ZodOptional; + introspectionEndpointAuthMethodsSupported: ZodOptional>; + introspectionEndpointAuthSigningAlgValuesSupported: ZodOptional>; + issuer: ZodString; + jwksUri: ZodOptional; + opPolicyUri: ZodOptional; + opTosUri: ZodOptional; + registrationEndpoint: ZodOptional; + responseModesSupported: ZodOptional>; + responseTypesSupported: ZodArray; + revocationEndpoint: ZodOptional; + revocationEndpointAuthMethodsSupported: ZodOptional>; + revocationEndpointAuthSigningAlgValuesSupported: ZodOptional>; + scopesSupported: ZodOptional>; + serviceDocumentation: ZodOptional; + tokenEndpoint: ZodString; + tokenEndpointAuthMethodsSupported: ZodOptional>; + tokenEndpointAuthSigningAlgValuesSupported: ZodOptional>; + uiLocalesSupported: ZodOptional>; + userinfoEndpoint: ZodOptional; +}, $strip>; ``` The camelCase version of the OAuth 2.0 Authorization Server Metadata Zod schema. -## See {#see} +## See [authorizationServerMetadataSchema](/references/js/variables/authorizationServerMetadataSchema.md) for the original schema and field information. diff --git a/docs/references/js/variables/camelCaseProtectedResourceMetadataSchema.md b/docs/references/js/variables/camelCaseProtectedResourceMetadataSchema.md index e79e1a0..603a8e9 100644 --- a/docs/references/js/variables/camelCaseProtectedResourceMetadataSchema.md +++ b/docs/references/js/variables/camelCaseProtectedResourceMetadataSchema.md @@ -5,11 +5,27 @@ sidebar_label: camelCaseProtectedResourceMetadataSchema # Variable: camelCaseProtectedResourceMetadataSchema ```ts -const camelCaseProtectedResourceMetadataSchema: ZodObject; +const camelCaseProtectedResourceMetadataSchema: ZodObject<{ + authorizationDetailsTypesSupported: ZodOptional>; + authorizationServers: ZodOptional>; + bearerMethodsSupported: ZodOptional>; + dpopBoundAccessTokensRequired: ZodOptional; + dpopSigningAlgValuesSupported: ZodOptional>; + jwksUri: ZodOptional; + resource: ZodString; + resourceDocumentation: ZodOptional; + resourceName: ZodOptional; + resourcePolicyUri: ZodOptional; + resourceSigningAlgValuesSupported: ZodOptional>; + resourceTosUri: ZodOptional; + scopesSupported: ZodOptional>; + signedMetadata: ZodOptional; + tlsClientCertificateBoundAccessTokens: ZodOptional; +}, $strip>; ``` The camelCase version of the OAuth 2.0 Protected Resource Metadata Zod schema. -## See {#see} +## See [protectedResourceMetadataSchema](/references/js/variables/protectedResourceMetadataSchema.md) for the original schema and field information. diff --git a/docs/references/js/variables/protectedResourceMetadataSchema.md b/docs/references/js/variables/protectedResourceMetadataSchema.md index c12270b..4b3236d 100644 --- a/docs/references/js/variables/protectedResourceMetadataSchema.md +++ b/docs/references/js/variables/protectedResourceMetadataSchema.md @@ -5,7 +5,23 @@ sidebar_label: protectedResourceMetadataSchema # Variable: protectedResourceMetadataSchema ```ts -const protectedResourceMetadataSchema: ZodObject; +const protectedResourceMetadataSchema: ZodObject<{ + authorization_details_types_supported: ZodOptional>; + authorization_servers: ZodOptional>; + bearer_methods_supported: ZodOptional>; + dpop_bound_access_tokens_required: ZodOptional; + dpop_signing_alg_values_supported: ZodOptional>; + jwks_uri: ZodOptional; + resource: ZodString; + resource_documentation: ZodOptional; + resource_name: ZodOptional; + resource_policy_uri: ZodOptional; + resource_signing_alg_values_supported: ZodOptional>; + resource_tos_uri: ZodOptional; + scopes_supported: ZodOptional>; + signed_metadata: ZodOptional; + tls_client_certificate_bound_access_tokens: ZodOptional; +}, $strip>; ``` Zod schema for OAuth 2.0 Protected Resource Metadata. diff --git a/typedoc.json b/typedoc.json index aa83e63..25f3905 100644 --- a/typedoc.json +++ b/typedoc.json @@ -5,9 +5,9 @@ "typedoc-plugin-frontmatter", "./typedoc-plugin-custom.mjs" ], - "tsconfig": "./sdk/js/packages/mcp-auth/tsconfig.build.json", + "tsconfig": "../sdk/js/packages/mcp-auth/tsconfig.build.json", "entryPoints": [ - "./sdk/js/packages/mcp-auth/src/index.ts", + "../sdk/js/packages/mcp-auth/src/index.ts", ], "name": "MCP Auth Node.js SDK reference", "out": "./docs/references/js",