@ttoss/http-server-mcp 0.15.0 → 0.16.1

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 
 /// <reference types="node" />
 import { Router } from "@ttoss/http-server";
+import { OAuthVerifyOptions } from "@ttoss/http-server-oauth";
 import { z } from "zod";
 import { McpServer, McpServer as McpServer$1 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
@@ -665,254 +666,23 @@ declare namespace Application {
   const HttpError: typeof HttpErrors.HttpError;
 }
 //#endregion
-//#region src/authServerTypes.d.ts
+//#region src/index.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.
+ * Authentication options for the MCP endpoint. Extends the `@ttoss/http-server`
+ * OAuth verification options with the optional protected-resource metadata
+ * endpoint that MCP clients fetch for discovery.
  */
-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;
-  };
+interface McpAuthOptions extends OAuthVerifyOptions {
+  /**
+   * URL of this MCP server, surfaced in the OAuth Protected Resource Metadata
+   * response. Both this and `authorizationServerUrl` must be set to serve
+   * `/.well-known/oauth-protected-resource`.
+   */
+  resourceServerUrl?: string;
+  /** URL of the OAuth Authorization Server that issues tokens for this resource. */
+  authorizationServerUrl?: 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.
  */
@@ -1004,58 +774,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
  */
@@ -1104,14 +822,17 @@ interface McpRouterOptions {
    * getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })
    * ```
    */
-  getApiHeaders?: (ctx: Context$2) => Record<string, string>;
+  getApiHeaders?: (ctx: Context$1) => 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
@@ -1252,64 +973,5 @@ interface RegisterToolFromSchemaParams {
  * ```
  */
 declare const registerToolFromSchema: (server: McpServer$1, params: RegisterToolFromSchemaParams) => void;
-/**
- * Returns the `WWW-Authenticate` header value for a 401 response on a
- * protected resource, following the MCP auth spec requirement that
- * unauthorized responses advertise the resource metadata URL so MCP
- * clients can bootstrap OAuth discovery.
- *
- * Use this in your own auth middleware when you are not using the built-in
- * `auth` option on `createMcpRouter`.
- *
- * @example
- * ```typescript
- * import { getWwwAuthenticateHeader } from '@ttoss/http-server-mcp';
- *
- * // Inside a Koa middleware
- * ctx.status = 401;
- * ctx.set('WWW-Authenticate', getWwwAuthenticateHeader({ resource: 'https://mcp.example.com' }));
- * ```
- */
-declare const getWwwAuthenticateHeader: (args: {
-  /**
-   * The resource server URL. The metadata URL is derived as
-   * `<resource>/.well-known/oauth-protected-resource` per RFC 9728.
-   */
-  resource: string;
-}) => string;
-/**
- * Creates a standalone Koa middleware that serves
- * `GET /.well-known/oauth-protected-resource` (RFC 9728) without requiring
- * the built-in `auth` option on `createMcpRouter`.
- *
- * Mount this **before** your own auth middleware so the discovery endpoint
- * remains unauthenticated (MCP clients fetch it before they have a token).
- *
- * @example
- * ```typescript
- * import Koa from 'koa';
- * import { createProtectedResourceMetadataMiddleware } from '@ttoss/http-server-mcp';
- *
- * const app = new Koa();
- * app.use(
- *   createProtectedResourceMetadataMiddleware({
- *     resource: 'https://mcp.example.com',
- *     authorizationServers: ['https://api.example.com'],
- *   })
- * );
- * app.use(myOwnAuthMiddleware);
- * ```
- */
-declare const createProtectedResourceMetadataMiddleware: (args: {
-  /**
-   * The protected resource's identifier URI (the MCP server URL).
-   */
-  resource: string;
-  /**
-   * List of authorization server issuer URIs that issue tokens for this
-   * resource.
-   */
-  authorizationServers: string[];
-}) => Application.Middleware;
 //#endregion
-export { ApiCallOptions, AuthCodeStore, AuthorizeRequest, ClientStore, CognitoUserPoolConfig, Context$1 as Context, IssueTokensArgs, IssuedTokens, JsonObjectSchema, McpAuthOptions, McpAuthServerOptions, McpRouterOptions, McpServer, OAuthClient, OAuthClientMetadata, OnAuthorizeArgs, OnAuthorizeResult, OnRefreshTokenArgs, OnRefreshTokenResult, RegisterToolFromSchemaParams, StoredAuthorizationCode, apiCall, checkScopes, createMcpAuthServer, createMcpRouter, createProtectedResourceMetadataMiddleware, getIdentity, getWwwAuthenticateHeader, registerToolFromSchema, z };
+export { ApiCallOptions, JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, RegisterToolFromSchemaParams, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };