@ttoss/http-server-mcp 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -665,8 +665,325 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
-//#region src/index.d.ts
+//#region src/auth.d.ts
+/** Amazon Cognito user pool configuration for JWT verification. */
+interface CognitoUserPoolConfig {
+  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
+  userPoolId: string;
+  /**
+   * Which token type to verify.
+   * @default 'access'
+   */
+  tokenUse?: 'access' | 'id';
+  /** The app client ID registered in the User Pool. */
+  clientId: string;
+}
+/**
+ * Authentication options for the MCP router.
+ *
+ * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
+ * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
+ */
+interface McpAuthOptions {
+  /**
+   * Amazon Cognito user pool config. When provided, the router creates a
+   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
+   */
+  cognitoUserPool?: CognitoUserPoolConfig;
+  /**
+   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
+   * Receives the raw Bearer token string. Should resolve with the verified
+   * payload or reject/throw on failure.
+   */
+  verifyToken?: (token: string) => Promise<unknown>;
+  /**
+   * Router-level scope guard. All listed scopes must be present on the token
+   * for any MCP request to be allowed. Returns 403 if any scope is missing.
+   *
+   * Cognito encodes scopes as a space-separated string in `payload.scope`.
+   *
+   * @example ['mcp:access']
+   */
+  requiredScopes?: string[];
+  /**
+   * URL of this MCP server, used in the OAuth Protected Resource Metadata
+   * response (`/.well-known/oauth-protected-resource`). Both this field and
+   * `authorizationServerUrl` must be provided to enable the endpoint.
+   */
+  resourceServerUrl?: string;
+  /**
+   * URL of the OAuth Authorization Server that issues tokens for this resource.
+   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
+   * (RFC 9728) when combined with `resourceServerUrl`.
+   */
+  authorizationServerUrl?: string;
+  /**
+   * JSON-RPC methods (read from `body.method`) that bypass token verification,
+   * so MCP clients can discover the server before authenticating. Set to an
+   * empty array to require a token for every method.
+   *
+   * @default ['initialize', 'tools/list']
+   */
+  publicMethods?: string[];
+  /**
+   * When set, a `401` from verification responds with
+   * `WWW-Authenticate: Bearer resource_metadata="<resourceMetadataUrl>"`
+   * (RFC 9728) so MCP clients can auto-discover the authorization server.
+   * When omitted, the header falls back to a bare `Bearer`.
+   *
+   * @example 'https://mcp.example.com/.well-known/oauth-protected-resource'
+   */
+  resourceMetadataUrl?: string;
+}
+//#endregion
+//#region src/authServerTypes.d.ts
 type Context$1 = Application.Context;
+/**
+ * OAuth 2.0 client metadata as supplied by a client during Dynamic Client
+ * Registration (RFC 7591). Apps may persist additional fields verbatim.
+ */
+interface OAuthClientMetadata {
+  /** Allowed redirect URIs. At least one is required for the auth-code flow. */
+  redirect_uris: string[];
+  /** Human-readable client name shown on consent screens. */
+  client_name?: string;
+  /** OAuth grant types the client will use. Defaults to auth-code + refresh. */
+  grant_types?: string[];
+  /** OAuth response types the client will use. Defaults to `['code']`. */
+  response_types?: string[];
+  /**
+   * Client authentication method at the token endpoint. `'none'` registers a
+   * public client (no secret issued); anything else registers a confidential
+   * client and a `client_secret` is generated.
+   */
+  token_endpoint_auth_method?: string;
+  /** Space-separated scopes the client may request. */
+  scope?: string;
+  [key: string]: unknown;
+}
+/**
+ * A registered OAuth client as persisted by the app's {@link ClientStore}.
+ */
+interface OAuthClient extends OAuthClientMetadata {
+  /** Unique client identifier issued by the authorization server. */
+  client_id: string;
+  /** Client secret for confidential clients. Absent for public clients. */
+  client_secret?: string;
+  /** Unix timestamp (seconds) when the client was registered. */
+  client_id_issued_at?: number;
+}
+/**
+ * App-provided store for OAuth clients. ttoss owns protocol mechanics; the app
+ * owns persistence (DynamoDB, Postgres, in-memory, …).
+ */
+interface ClientStore {
+  /** Look up a client by its `client_id`. Return `undefined` if unknown. */
+  get: (clientId: string) => Promise<OAuthClient | undefined> | OAuthClient | undefined;
+  /** Persist a newly registered client. */
+  register: (client: OAuthClient) => Promise<void> | void;
+}
+/**
+ * A short-lived authorization code with its bound PKCE challenge and the
+ * details needed to issue tokens when the code is later exchanged.
+ */
+interface StoredAuthorizationCode {
+  /** The opaque authorization code value. */
+  code: string;
+  /** The `client_id` the code was issued to. */
+  clientId: string;
+  /** The redirect URI the code was issued for (must match on exchange). */
+  redirectUri: string;
+  /** The PKCE `code_challenge` (S256) bound to this code. */
+  codeChallenge: string;
+  /** The scopes granted to this code. */
+  scopes: string[];
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** Unix timestamp (milliseconds) after which the code is invalid. */
+  expiresAt: number;
+}
+/**
+ * App-provided store for authorization codes. Codes are single-use and
+ * short-lived; the app decides where to persist them.
+ */
+interface AuthCodeStore {
+  /** Persist an authorization code. */
+  save: (code: StoredAuthorizationCode) => Promise<void> | void;
+  /** Look up an authorization code by its value. */
+  get: (code: string) => Promise<StoredAuthorizationCode | undefined> | StoredAuthorizationCode | undefined;
+  /** Remove an authorization code (called on exchange to enforce single use). */
+  delete: (code: string) => Promise<void> | void;
+}
+/** Tokens returned by the app's {@link McpAuthServerOptions.issueTokens} hook. */
+interface IssuedTokens {
+  /** The access token string (JWT, opaque, …). */
+  accessToken: string;
+  /** Optional refresh token enabling the `refresh_token` grant. */
+  refreshToken?: string;
+  /** Access token lifetime in seconds, surfaced as `expires_in`. */
+  expiresIn?: number;
+  /** Granted scopes as a space-separated string. Defaults to the bound scopes. */
+  scope?: string;
+}
+/** Arguments passed to {@link McpAuthServerOptions.issueTokens}. */
+interface IssueTokensArgs {
+  /** The authenticated end-user subject identifier. */
+  subject: string;
+  /** The scopes granted to the token. */
+  scopes: string[];
+  /** The client the tokens are being issued to. */
+  client: OAuthClient;
+}
+/** The validated authorization request passed to the consent/login hook. */
+interface AuthorizeRequest {
+  /** The requesting `client_id`. */
+  clientId: string;
+  /** The validated redirect URI. */
+  redirectUri: string;
+  /** The requested scopes. */
+  scopes: string[];
+  /** Opaque CSRF/state value to echo back on redirect. */
+  state?: string;
+  /** The PKCE `code_challenge`. */
+  codeChallenge: string;
+  /** The PKCE challenge method (always `'S256'`). */
+  codeChallengeMethod: string;
+}
+/** Arguments passed to {@link McpAuthServerOptions.onAuthorize}. */
+interface OnAuthorizeArgs {
+  /** The Koa context, so the app can read cookies/session or write a response. */
+  ctx: Context$1;
+  /** The resolved client making the request. */
+  client: OAuthClient;
+  /** The validated authorization request. */
+  request: AuthorizeRequest;
+}
+/**
+ * Result of the app's consent/login hook.
+ *
+ * `approved: true` means the end-user is authenticated and has consented — the
+ * authorization server issues a code and redirects. `approved: false` means the
+ * app has taken over the response (e.g. redirected to its own login/consent
+ * page); the authorization server does nothing further.
+ */
+type OnAuthorizeResult = {
+  approved: true;
+  subject: string;
+  scopes?: string[];
+} | {
+  approved: false;
+};
+/** Arguments passed to {@link McpAuthServerOptions.onRefreshToken}. */
+interface OnRefreshTokenArgs {
+  /** The refresh token presented by the client. */
+  refreshToken: string;
+  /** The authenticated client. */
+  client: OAuthClient;
+  /** Scopes requested in the refresh request (may be empty). */
+  scopes: string[];
+}
+/**
+ * Result of validating a refresh token. Return `undefined` to reject the token.
+ */
+type OnRefreshTokenResult = {
+  subject: string;
+  scopes: string[];
+} | undefined;
+/** Configuration for {@link createMcpAuthServer}. */
+interface McpAuthServerOptions {
+  /** The authorization server's issuer identifier (its base URL). */
+  issuer: string;
+  /** App-provided store for dynamic clients. */
+  clientStore: ClientStore;
+  /** App-provided store for short-lived authorization codes. */
+  authCodeStore: AuthCodeStore;
+  /**
+   * App-owned token minting. ttoss never sees the user model or signing keys —
+   * it hands you the subject/scopes/client and you return the tokens.
+   */
+  issueTokens: (args: IssueTokensArgs) => Promise<IssuedTokens> | IssuedTokens;
+  /**
+   * App-owned login/consent. Called on every `/authorize` request; return the
+   * authenticated subject to approve, or take over the response to show your
+   * own login/consent UI and return `{ approved: false }`.
+   */
+  onAuthorize: (args: OnAuthorizeArgs) => Promise<OnAuthorizeResult> | OnAuthorizeResult;
+  /**
+   * App-owned refresh-token validation. Required to support the `refresh_token`
+   * grant; when omitted, refresh requests get `unsupported_grant_type`.
+   */
+  onRefreshToken?: (args: OnRefreshTokenArgs) => Promise<OnRefreshTokenResult> | OnRefreshTokenResult;
+  /** Scopes advertised in discovery metadata (`scopes_supported`). */
+  scopesSupported?: string[];
+  /**
+   * When set, also serves `/.well-known/oauth-protected-resource` (RFC 9728)
+   * pairing this resource URL with the issuer as its authorization server.
+   */
+  resource?: string;
+  /**
+   * Authorization code lifetime in seconds.
+   * @default 600
+   */
+  authorizationCodeTtl?: number;
+  /** Override the default endpoint paths. */
+  endpoints?: {
+    /** @default '/authorize' */authorize?: string; /** @default '/token' */
+    token?: string; /** @default '/register' */
+    register?: string;
+  };
+}
+//#endregion
+//#region src/authServer.d.ts
+/**
+ * Creates transport-agnostic OAuth 2.1 Authorization Server primitives for MCP.
+ *
+ * Mounts the authorization endpoint (`/authorize`, PKCE S256 required), token
+ * endpoint (`/token`, `authorization_code` + `refresh_token` grants), Dynamic
+ * Client Registration (`/register`, RFC 7591), and AS metadata discovery
+ * (`/.well-known/oauth-authorization-server`, RFC 8414). When `resource` is
+ * set, it also serves the protected-resource metadata (RFC 9728).
+ *
+ * ttoss owns only the protocol mechanics — the app supplies its own stores,
+ * token signing/verification, and login/consent UI through the option hooks, so
+ * the user model, JWT/IAM, and authentication never leave the consuming app.
+ *
+ * @param options - Authorization server configuration and pluggable hooks.
+ * @returns A Koa `Router` exposing `routes()` / `allowedMethods()`.
+ *
+ * @example
+ * ```typescript
+ * import { App, bodyParser } from '@ttoss/http-server';
+ * import { createMcpAuthServer } from '@ttoss/http-server-mcp';
+ *
+ * const authServer = createMcpAuthServer({
+ *   issuer: 'https://api.soat.dev',
+ *   clientStore,
+ *   authCodeStore,
+ *   issueTokens: async ({ subject, scopes }) => ({
+ *     accessToken: signJwt({ sub: subject, scope: scopes.join(' ') }),
+ *     refreshToken: createRefreshToken(subject),
+ *     expiresIn: 3600,
+ *   }),
+ *   onAuthorize: async ({ ctx }) => {
+ *     const session = await getSession(ctx);
+ *     if (!session) {
+ *       ctx.redirect('/login');
+ *       return { approved: false };
+ *     }
+ *     return { approved: true, subject: session.userId };
+ *   },
+ *   scopesSupported: ['mcp:access'],
+ * });
+ *
+ * const app = new App();
+ * app.use(bodyParser());
+ * app.use(authServer.routes());
+ * ```
+ */
+declare const createMcpAuthServer: (options: McpAuthServerOptions) => Router;
+//#endregion
+//#region src/index.d.ts
+type Context$2 = Application.Context;
 /**
  * Options for a single `apiCall` request.
  */
@@ -758,58 +1075,6 @@ declare const getIdentity: () => unknown;
  * ```
  */
 declare const checkScopes: (required: string[]) => void;
-/** Amazon Cognito user pool configuration for JWT verification. */
-interface CognitoUserPoolConfig {
-  /** The Cognito User Pool ID (e.g. `us-east-1_abc123`). */
-  userPoolId: string;
-  /**
-   * Which token type to verify.
-   * @default 'access'
-   */
-  tokenUse?: 'access' | 'id';
-  /** The app client ID registered in the User Pool. */
-  clientId: string;
-}
-/**
- * Authentication options for the MCP router.
- *
- * Supply either `cognitoUserPool` (uses `CognitoJwtVerifier` from
- * `@ttoss/auth-core`) or a custom `verifyToken` function — not both.
- */
-interface McpAuthOptions {
-  /**
-   * Amazon Cognito user pool config. When provided, the router creates a
-   * `CognitoJwtVerifier` and validates every incoming Bearer token against it.
-   */
-  cognitoUserPool?: CognitoUserPoolConfig;
-  /**
-   * Custom token verifier for non-Cognito providers (Auth0, Keycloak, …).
-   * Receives the raw Bearer token string. Should resolve with the verified
-   * payload or reject/throw on failure.
-   */
-  verifyToken?: (token: string) => Promise<unknown>;
-  /**
-   * Router-level scope guard. All listed scopes must be present on the token
-   * for any MCP request to be allowed. Returns 403 if any scope is missing.
-   *
-   * Cognito encodes scopes as a space-separated string in `payload.scope`.
-   *
-   * @example ['mcp:access']
-   */
-  requiredScopes?: string[];
-  /**
-   * URL of this MCP server, used in the OAuth Protected Resource Metadata
-   * response (`/.well-known/oauth-protected-resource`). Both this field and
-   * `authorizationServerUrl` must be provided to enable the endpoint.
-   */
-  resourceServerUrl?: string;
-  /**
-   * URL of the OAuth Authorization Server that issues tokens for this resource.
-   * Enables `/.well-known/oauth-protected-resource` for MCP client auto-discovery
-   * (RFC 9728) when combined with `resourceServerUrl`.
-   */
-  authorizationServerUrl?: string;
-}
 /**
  * Options for configuring the MCP router
  */
@@ -858,14 +1123,17 @@ interface McpRouterOptions {
    * getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })
    * ```
    */
-  getApiHeaders?: (ctx: Context$1) => Record<string, string>;
+  getApiHeaders?: (ctx: Context$2) => Record<string, string>;
   /**
    * OAuth / JWT authentication configuration for the MCP endpoint.
    *
-   * When set, every incoming MCP request must include a valid Bearer token in
-   * the `Authorization` header. Invalid or missing tokens receive a `401`
-   * response with `WWW-Authenticate: Bearer`. Tokens that fail a
-   * `requiredScopes` check receive `403`.
+   * When set, incoming MCP requests must include a valid Bearer token in the
+   * `Authorization` header — except for `publicMethods` (by default
+   * `initialize` and `tools/list`), which bypass verification so clients can
+   * discover the server before authenticating. Invalid or missing tokens
+   * receive a `401` response with `WWW-Authenticate: Bearer` (or
+   * `Bearer resource_metadata="..."` when `resourceMetadataUrl` is set, per
+   * RFC 9728). Tokens that fail a `requiredScopes` check receive `403`.
    *
    * The verified token payload is accessible inside tool handlers via
    * {@link getIdentity}. Fine-grained per-tool scope checks can be done with
@@ -1066,4 +1334,4 @@ declare const createProtectedResourceMetadataMiddleware: (args: {
   authorizationServers: string[];
 }) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };
+export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, type CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, type McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };